Using the Photon microGUI

This chapter includes:

• Overview of Photon
• Modifying the shelf
• Modifying the Launch menu
• Modifying the Desktop menu
• Starting applications automatically
• Configuration tools
• Browsing files with the File Manager
• Getting help with the Helpviewer
• Surfing the web with Voyager
• Connecting to other systems
• Hotkeys and shortcuts
• Photon environment variables
• Troubleshooting

Overview of Photon

The Photon microGUI is Neutrino's graphical user interface, and you can use it as a desktop environment, similar to other GUI desktop environments. This means you can run applications in windows, use the mouse for point-and-click and dragging operations, view directories and files graphically in a tree hierarchy, view multimedia files, and so on. Photon also provides the framework for graphical applications in embedded systems.

Many of the applications and utilities that come with Photon are documented in the Neutrino Utilities Reference. For information about programming Photon applications, see the Photon Programmer's Guide.

Why is it called "Photon"?

Whenever you use your mouse or press a key, you're giving input to a Photon application. And whenever the application displays data in a window, it's providing output. All these interactions are processed as tiny packets of data called events. You can think of all these input and output events traveling between you and Photon applications as photons, particles of light.

Why is it called a "microGUI"?

We call Photon a "microGUI" because of its size and architecture. Photon is a very small GUI. It's designed to fit in embedded systems, but it's also designed to be scaled up. Photon is perfectly at home in high-end, high-performance distributed systems.

Like Neutrino itself, Photon is built around a small microkernel. This modular architecture makes Photon fast, flexible, and inherently capable of network-distributed computing.

Your workspace

When you start Photon for the first time, you're prompted to set up your graphics card and settings.

When Photon starts, you see your workspace, which is an area where you can run applications. The workspace consists of the taskbar, the shelf, and the desktop:

Photon's workspace, including the taskbar, shelf, and desktop.

The desktop is the main part of the screen. It's where application windows appear. In Photon, the desktop is actually a view, called a virtual console, into a much larger desktop space, which is three desktops wide by three desktops high. You can run applications in different consoles, and switch consoles by using keyboard shortcuts or the World View in the shelf.

If you right-click anywhere on the desktop, you see the Desktop Menu, which lets you easily run frequently used applications, configure Photon, or shut down. You can customize this menu (see below).

Desktop menu.

The taskbar is the area at the very bottom of the screen. It includes, by default, the Launch button, the date and time, and icons for applications that are currently running.

From the taskbar, you can:

• click an application icon on the taskbar to hide or show the application
• click the Launch button to launch an application, get help, or shut down the Photon session.

The shelf runs up the right side of your screen, and lets you easily launch frequently used applications and utilities, configure your system, view system resource usage, and switch consoles.

From the shelf, you can:

• toggle the appearance of shelf components by clicking on the component category. An expanded component category appears with a + next to it, while a collapsed category appears with a -.
• launch an application, utility, or configuration utility by clicking on its icon
• change the current console by clicking on a console in the World View

  ---

  You can also switch your console by pressing Ctrl-Alt-1...9, where the number is the console number.

  ---

• control the CD Player.

Right-click anywhere on the taskbar or shelf to configure or exit the shelf application. To run or restart shelf, type shelf & at a command line.

Drag the taskbar or shelf border to make it smaller or larger. If you drag the border to the bottom or right of the screen, the taskbar or shelf is put in autoshow mode, which means it appears only when you move the mouse over the edge of the screen.

Modifying the shelf

You can configure the shelf by right-clicking on the shelf or taskbar and selecting Setup or by running shelf -c from the command line. The shelf's configuration dialog looks like this:

Shelf configuration dialog.

When you configure your shelf, the new settings are saved for the current user only. Your shelf configuration file is stored in your home directory, under $HOME/.ph/shelf/shelf.cfg. The first time you log in, the default version of /etc/photon/shelf/shelf.cfg is copied to $HOME/.ph/shelf/shelf.cfg.

The items you can add or modify on the shelf include:

Group

A group of applications or utilities. A group can contain child groups.

Drawer

Like a group, but a drawer expands horizontally out of its parent container rather than vertically in the shelf.

Separator

A space that visually separates two containers. Any space not used in a shelf is occupied by a separator, so you always have at least one separator per shelf. If you try to remove a separator, it's repositioned.

World view

A world view plugin, which lets you see which consoles contain open windows, and lets you set the current console.

CD player

A CD-player plugin.

Volume

A volume-control plugin.

You can choose additional plugins by selecting the Browse button, including:

cdplayer.so

You can play a CD, stop, skip forward, and skip back. The plugin displays the track information in its text box.

clock.so

You can choose the clock's font and its size, whether or not to show the date and the seconds, and the format of the date (AM/PM).

If you select this plugin from the shelf, it opens a User Configuration utility that lets you set and manage the time and date.

launcher.so

A plugin that lets you create on the shelf an item that runs an arbitrary command.

launchmenu.so

A plugin that supports the Launch menu. You can have only one of these in your shelf at any given time. If you try to add a second one into your shelf, it's ignored. If you want to change the location of the Launch menu, you must first remove the original and then add the new one in the new location.

Note that this plugin doesn't work in a drawer; it must be at the top level in a shelf. For information about specifying the contents of the Launch menu, see "Modifying the Launch menu," below.

led.so

A set of three "LEDs" that show which of the Num Lock, Caps Lock, and Scroll Lock keys are on. The light is on when the key is active.

pload.so

A CPU Load Monitor that displays bar graphs that indicate the levels of CPU usage, memory usage, and disk and network activity.

ptrcam.so

A "pointer cam" that magnifies the image directly under the pointer. You can specify the horizontal and vertical radius, in pixels.

taskbar.so

The taskbar that lets you switch between applications simply by selecting their icons. You can change the font, font size, active and inactive colors, and you can decide whether or not to display balloons when you hover over an entry.

volume.so

A slider that controls the volume coming from the sound card. To mute and unmute the volume, select the small speaker icon in this plugin.

worldview.so

A miniature version of your nine virtual consoles. You can decide when to display window frames: always, never, or depending on the size of the world view.

Modifying the Launch menu

The launchmenu.so plugin populates the Launch menu, based on the contents of the $HOME/.ph/launchmenu and /etc/photon/launchmenu directories.

If there are conflicting items, the item found first prevails, so items encountered in your home directory's launchmenu directory take precedence over items encountered in the global one.

Creating items and submenus

Inside $HOME/.ph/launchmenu and /etc/photon/launchmenu, each directory corresponds to a submenu, and each file or symbolic link corresponds to a menu item, with the following exceptions:

• Files named .menu contain special menu-formatting commands; see "Additional menu control," below.
• Items with a .tgt extension specify runnable targets within; see "Target files," below.
• Other items beginning with a period (.) are ignored.

For all other files, the plugin creates a menu item. Here's what happens when you select an item:

• If the file is a symbolic link, it's resolved to the file that it points to.
• If the file is executable, the plugin executes it.
• If the file isn't executable, the plugin tries to determine an appropriate viewer for the file, using the Photon file-association mechanism (see pfm in the Utilities Reference).
• Failing all else, selecting the item does nothing.

For all items (except *.tgt files), the launchmenu.so plugin uses the filename as the text to display for that item. You can use any characters in the filename (within the constraints of the underlying filesystem); the plugin assumes that these filenames use UTF-8 encoding.

The ampersand (&) takes on special meaning; the plugin interprets the character that follows as an accelerator key for that item. If you want to display a literal ampersand, specify it as && in the filename.

Target files

The launchmenu.so plugin uses target (*.tgt) files to give you more control than simple files give over launchable targets and how they're represented within the menu. You can use target files to specify one (or more) runnable targets, where each target corresponds to a single menu item. You specify the targets in this form:

[item1_text]
target = action
...
[item2_text]
target = action
...

Target files are organized into one or more sections, where each section specifies a target. The square brackets are part of the syntax; the text in them is the menu item's default text, following the same conventions as discussed above for filenames.

Each target is described by key=value pairs within the section. You must specify the target=action pair; it specifies what to do when the item is invoked. The action can be one of:

• a full path to another file or directory. The launchmenu.so plugin examines that file and treats it accordingly; it could be an executable, a regular file, directory, or even another target file.
• a filename of an executable that can be found by searching the directories specified in your PATH environment variable
• a shell-style command in the form:

  env1=val1... command options
      

If you don't specify the target key, the plugin ignores the section when it's generating menu items.

The optional keys are:

sicon

The full path of a small (maximum 24 * 18 pixels) icon to display for the item. If you don't specify this, the launchmenu.so plugin tries to find an icon using the association mechanism, or from the executable if the item is a PhAB application.

licon

The full path of a large (maximum 48 * 48 pixels) icon to display for the item.

group

This entry lets you logically group items from different target files, for use when ordering the items. For more information, see "Controlling the order of items," below.

order

This entry lets you specify the order of the items, generally in conjunction with the group entry.

As mentioned above, the section name specifies the default text displayed for the item. If you want to provide items in multiple languages, you can specify an entry whose key is a language code as used by the ABLANG environment variable (see the International Language Support chapter of the Photon Programmer's Guide), and whose key is the text in that language. For example:

[Calculator]
target = phcalc
fr_FR = Calculatrice

Controlling the order of items

By default, the launchmenu.so plugin sorts items alphanumerically by the displayed text. However, it also provides a degree of control over item ordering within the target specification. If you're shipping a package that includes a number of items to be included in a menu and you want them to be ordered in a specific manner regardless of their names (for instance, you deem some items to be more important and want to ensure they appear first), you can control this ordering in one of these ways:

Multiple target files

If the targets are spread across multiple target files for any reason, you need to establish a logical grouping to sort the items in. You do this by specifying a group entry in the target. The value for this entry may be any string, although we recommend you follow this convention to avoid potential conflicts:

Company name:Product Family:Name

In most cases, the company name alone should suffice, although you may wish to be more specific, depending on the number of product lines you offer.

After the plugin groups the items logically via the group entry, it sorts the items alphanumerically by the order entry. The order can be any string; you can simply use numbers, or you can choose a more elaborate scheme that will let you insert other items in the future.

Single target file

Items specified in a single file can take advantage of implicit ordering. That is, in absence of a group entry, they automatically inherit a value that's also available to all other targets within the same file. In this case, you need to specify only the order entry, as described above.

Additional menu control

Directories, files, and targets provide all the mechanisms necessary for populating menus with content, and even allow for a degree of control in terms of ordering. You can also use menu format-control files (named .menu) to fine-tune overall menu presentation and visually group related items.

Menu format is specified as a PxConfig-style file (see the Photon Library Reference), with each section specifying some form of control. The types of control are:

• Item Placement -- this lets you control the overall ordering of menu items further. To do this, specify an item name (or pattern to match -- see fnmatch() in the Neutrino Library Reference) as the section name. You can provide a section name in other languages by including an entry with a language code as the key, as described earlier.

  In the simplest case, the section has no entries, but you can also use the type entry to further specify which type of item to apply the match to. By default, the matching is applied to all items, but you may be more exclusive and supply specific types by grouping one or more of the following symbols as this entry's value:

  a

  All types (this is the default behavior).

  c

  Command-type items (shell-style command, as discussed above).

  d

  Directory items (submenus).

  e

  Executables (items that can be executed directly without parsing or use of a third-party viewer).

  f

  Files (items that can't be executed directly; they need a viewer).

  For example, this code first groups all the submenu items, followed by everything else:

  [*]
  type = d
  [*]
  type = cef

• Separators -- these let you specify visual separations in your menus. The section name must begin with a hyphen (-). The plugin ignores any additional text in the name and any entries in the section.

  For example, this code separates the submenus from the rest of the items:

  [*]
  type = d
  [-]
  [*]
  type = cef
    

  ---

  The launchmenu.so plugin won't place a separator at the start or end of the menu, or next to another separator.

  ---

• Inlined targets -- as with target files, you can specify targets within the .menu file. See the above section on target files for how to do this.

Troubleshooting

How can I bind an icon to a submenu? How can I supply alternate text for a submenu item (say, to translate it into a different language)?

The launchmenu.so plugin ignores files whose names begin with a period (.), so the first step is to hide the directory by adding a period to the beginning of its name. Next, create a file with an extension of .tgt (the name doesn't matter, as long as it doesn't begin with a period). In the target field, specify the full path to your new, hidden directory. You can then specify any additional information, such as icons and translations.

Can I use files from elsewhere in the filesystem to build a menu?

Yes, you can. For example, you can put a symbolic link into $HOME/.ph/launchmenu that points elsewhere in the filesystem. Note that because the plugin has to scan the files and build a hierarchy based on the contents, this can take a while to complete, depending on the number of files and subdirectories that the plugin encounters.

I've edited a target file. How do I get the Launch menu to reflect the change?

The launchmenu.so plugin watches only directories for changes, because watching all of the files could take too time. In addition, directories are typically updated as items are installed and uninstalled, so if an entry is added or removed from a directory, the plugin picks it up on-the-fly. If you've changed a file, and you want the change to take effect immediately, you can:

• restart the shelf (type shelf & on the command line).

  Or:

• touch the directory containing the item. The launchmenu.so plugin refreshes the corresponding submenu.

What about packages installed with the old installer? Will they show up?

The launchmenu_notify utility creates a .tgt file that represents legacy and third-party packages.

I've installed a package with the old installer, but I'm not getting a launchmenu item. What should I do?

Try the following:

1. Run launchmenu_notify -vvv from the command line. This tells you which third-party or legacy items exist, need to be added, and can be removed.
2. Examine the list of existing items to see if one matches the missing item. If an item doesn't appear in the Launch menu, the target likely doesn't specify a valid file (e.g. the file doesn't exist).

If this doesn't help you solve the problem, please let us know.

I've created my own item, but it doesn't appear in the Launch menu.

The target might not specify a valid, existing file. The launchmenu.so plugin doesn't display items that don't have a target, or that have a target that can't be resolved. Make sure the target is either a full path or an executable that the shell can find (use the which utility to determine this).

Modifying the Desktop menu

The Desktop menu is the one that pops up when you right-click anywhere on the Photon desktop.

You can run phmenu from the command line by typing phmenu &. This utility lets you drag and drop the menu items to the trash or to a new location. When the item is selected, you can modify the label shown in the menu, the hotkey, and the command to run. You can add new items by selecting the item you would like and dropping it into the desired location in the tree.

For more information, see phmenu and pwm in the Utilities Reference.

Starting applications automatically

You can tell Photon to launch applications on startup. To do this, add the name of the application's executable to the $HOME/.ph/phapps configuration file. For example:

ped &
pterm &
helpviewer &

If the file doesn't exist, you need to create it, and make it executable by changing its properties with the File Manager, or by typing chmod +x ~/.ph/phapps.

Configuration tools

Photon provides various configuration tools that let you change your Photon settings. You can run them all from the command line, and some you can start from the shelf or Launch menu.

Appearance: pwmopts, Appearance in the shelf, or Launch-->Configure-->Appearance

Select the background colors, pattern, and image settings, as well as title alignment and window behavior, including whether to:

• drag a full window or just its outline
• assign keyboard focus by clicking in a window or have focus follow your pointer
• bring a window to the front by clicking in it.

Select the Background tab to set the desktop color and pattern, or to select an image for the desktop backdrop.

Fonts: fontadmin

Map font substitutions, set options such as anti-aliasing, and configure Asian identification. For more information, see "The right fonts" in Configuring Your Environment.

Graphics: phgrafx, Graphics in the shelf, or Launch-->Configure-->Graphics

Select graphics settings for Photon. When you run phgrafx, you can select from a list of available graphics modes for each video driver supported by your graphics card. The list is generated by a hardware scan Photon performs during installation.

Localization: phlocale, Localization or Time & Date in the shelf, or Launch-->Configure-->Localization

Set your machine's time zone, language, keyboard (see "International keyboards" in Using the Command Line), time, and date.

---

Changing the language on your machine affects only the applications that support your choice. Other applications continue to use their default language.

---

Mouse: input-cfg, Mouse in the shelf, or Launch-->Configure-->Mouse

Set the speed and acceleration of the mouse pointer. You can also swap the buttons (to reduce the strain if you're using the mouse with your left hand) and enable the wheel if the mouse has one.

Network: phlip, Network in the shelf, or Launch-->Configure-->Network

Manage your network and modem settings.

Print manager: prjobs

View, start, or cancel jobs in the print queue.

Remote access: phrelaycfg

Create or delete the /etc/system/config/noditto file, which prevents anyone from using phditto to access your Photon workspace from a remote machine.

Screen saver: savercfg, Screen Saver in the shelf, or Launch-->Configure-->Screen Saver

Configure the Photon screen saver. You can select from a list of screen savers, and set the activation time, a password, and any command-line options that the selected screen saver might have.

Browsing files with the File Manager

Photon comes with a file manager, pfm, that lets you browse directories and files using a graphical interface. To open the Photon File Manager, click File Manager in the Applications group on the shelf, or type pfm & on the command line.

Photon File Manager.

The Photon File manager represents files and folders graphically. Double-click a folder to open it and display its contents; double-click a file to open it in an associated application (if an association exists). The File Manager also supports drag-and-drop operations; for example, you can drag a file to a folder to move it there. You can right-click a file or folder to view a shortcut menu that contains the available commands.

At the top of the File Manager are two text boxes that you can use to navigate and filter directory listings. You can type a path name directly into the Path box to jump to that directory. To view only files of a certain type or that start with a specific character, use the Filter box. For example, enter p* to view only files that start with the letter p, or enter *.ps to view only files that have the .ps suffix.

You can use the Photon File Manager menus to perform many file-management tasks. The toolbar at the top of the File Manager provides shortcuts for some commonly used commands. For more information, see pfm in the Utilities Reference.

You can view a listing of the most common keyboard shortcuts in File Manager by selecting Help-->Quick Reference. You can also view all currently defined bookmarks in a panel by clicking the Bookmarks toolbar shortcut.

Some of these commands are also available from the right-click menu in File Manager.

Getting help with the Helpviewer

You can use the Photon Helpviewer to display our product documentation. The documentation is organized under the /usr/help/product directory.

To open the Helpviewer, click the Help button in the Applications group on the shelf, or select Help from the right-click shortcut menu on the desktop. You can also start the helpviewer by typing helpviewer & on the command line.

The Photon helpviewer.

In the Topics list, click the arrow next to a topic to view the subtopics it contains, or double-click a topic to make it the top topic in the list. Clicking on a topic displays its content in the topic pane.

You can also browse to topics by clicking on hypertext links within the topic text. Links are indicated by color and underline.

Searching for a topic or keyword

You can search for words in the help files by using the Find feature. The Find panel is located under the Topics list. If it isn't visible, select View-->Topics, or press Ctrl-T. Enter the word(s) in the Find box and click Go!. If you enter multiple terms, helpviewer finds topics that contain all the terms.

You might need to generate a full-text search index on a set of help files if one doesn't exist. To do so, select File-->Generate Index. For large help sets, such as Neutrino's, this operation can take several minutes.

You can refine the search by selecting one or more of these find options:

Match Whole Words

Check this box to match whole words. If unchecked, partial word matches are found. For example, "grep" also matches "egrep".

Case Sensitive

Check this box to match the case in the search terms.

Search Topic Text

Check this box to search all the text in a topic. If unchecked, only topic headings are searched.

Search All Topics

Check this box to search all the topics in the help set.

The pterm terminal window lets you select (highlight) a portion of text and then invoke the Helpviewer by either:

• pressing the right mouse button to bring up the pterm menu and selecting Search help

  or:

• pressing Ctrl-Alt-H.

The Helpviewer starts, then searches the table of contents for any topics that contain the selected text. The first matching topic is automatically displayed.

You can also simply type something in a pterm window and then press Ctrl-Alt-H.

Most QNX documents include a keyword index that can also help you find what you're looking for. In the online docs, click the keyword-index button, which appears at the top and bottom of each file:

Bookmarking a topic to view it again later

If you find a topic that you want to view again later, you can bookmark it. This saves a quick link to that topic in the bookmarks list. To bookmark your current topic, select Bookmarks-->Add Bookmarks.

To view the list, click the Bookmarks toolbar button. Click an item in the list to view the topic. Bookmarks also appear in the Bookmark menu.

You can remove bookmarks by viewing the bookmarked topic, and then selecting Bookmarks-->Remove Bookmark.

Navigating around help files

The Helpviewer provides the following ways to navigate through the documentation:

The online documentation also includes some navigation buttons at the top and bottom of each file:

Navigation buttons in the online docs.

The Contents button moves you "up" in the document:

• In a prose book, it typically takes you to About This Guide.
• In a reference book, it takes you to the listing of items that start with a given letter. For example, if you're looking at the docs for abs(), this button takes you to the list of the functions that start with A.

Viewing more than one topic at once

You can view several topics at once by opening topics in a new topic window. Each open topic window is indicated by a tab above the topic pane.

To open a new topic pane, select File-->New Section, or press Ctrl-N. You can view any open topic by clicking on its tab. To close the current topic, select File-->Close Section, or press Ctrl-D.

Surfing the web with Voyager

Photon ships with a web browser called Voyager that you can use to browse local HTML files or to browse the Internet.

Neutrino also includes an embedded web server called Slinger that you can use to build Internet access into embedded systems. For more information, see the Setting Up an Embedded Web Server chapter.

To start Voyager, right-click anywhere on the desktop and select Voyager, or type voyager & at a pterm prompt.

The Voyager browser.

At the top of the Voyager window, you'll find a menubar, a toolbar, and site bar. At the bottom of the window is a status bar that displays the current document security status, which items are being loaded, and the current encoding setting; if you hover over a link, the link destination appears in the status bar. You can turn the toolbar, site bar, and status on or off.

Voyager supports several common image and multimedia file types, including .jpg, .gif, and .png (for images) and .mpg, .wav, .au, .aif, .mp3, .mp1, .mp2, .mpa, .mpv and .m2p (for audio and video).

You can view a Quick Reference Guide in Voyager at any time by clicking Help-->Quick Reference. For more information about using Voyager, see voyager in the Utilities Reference.

Setting preferences

To set your preferences for Voyager, select Edit-->Preferences. The configuration dialog includes these tabs:

• Cache
• Appearance
• Connection
• Information
• Print
• Applications

You can configure Voyager to use different rendering engines, such as vserver, netfront, or Mozilla. Some preferences are specific to the rendering engine. See voyager in the Utilities Reference for more information about specifying a rendering engine (or web server) using web server profiles.

Cache tab

Caching can help Voyager display files and images faster. In addition to the disk cache size, you can specify:

Image Cache Size

The image cache holds all images rendered to the screen. If you find web pages with images not displayed, or you have a high-color monitor with a high-color graphics driver running and the Use 256 colors only button is disabled, you may need to increase the image cache size.

Cache n Pages

Voyager might run faster if you have a large number of web pages cached; however, increasing the number of cached pages might use more memory.

Cache Verify Policy

How often you want Voyager to compare the web page in the cache with the version on the Internet.

Voyager doesn't refresh its versions of files that are on your network (i.e. URLs that start with file instead of http). If a file has been changed, click Reload to see the updated version.

Appearance tab

In this part of the configuration dialog, you can specify:

• the colors to use for links, active links, visited links, text, and background -- click an option's color swatch to view a selector to set the color for that option
• the font for text, headings, and fixed-width text
• the default text size for a web page
• whether you want the toolbar to include just icons, just text, or both.

If the browser is using the netfront server, these options are also available:

• the scrollbar size, in pixels
• whether you want the browser to disable pop-up windows generated by JavaScript.

Connection tab

In this part of Voyager's configuration dialog, you can specify the following:

Use Proxy Server

Enable this item if you use a proxy server(s) for HTTP, FTP, or Gopher, or if you use a SOCKS host to connect to the Internet.

Max Connections

The maximum number of connections to the Internet allowed at any one time.

HTTP Proxy

The IP address of the HTTP proxy server and the port number in the adjacent field.

FTP Proxy

The IP address of the FTP proxy server and the port number in the adjacent field.

Gopher Proxy

The IP address of the Gopher proxy server and the port number in the adjacent field.

SOCKS Host

The IP address of the SOCKS host and the port number in the adjacent field.

Proxy Overrides

The IP addresses of host computers that shouldn't go through the proxy server(s). Separate the hosts with commas. Wildcards are supported.

To find out the correct settings, see your Internet Service Provider (ISP) or system administrator.

Information tab

You can specify the following in this part of the configuration dialog:

Home Page

The complete URL of the web page you'd like to appear each time you start Voyager. Restart Voyager for the new home page to take effect.

Email Address

Your email address.

Email Server

The IP address of your SMTP server (e.g. news.qnx.com or 10.0.0.100).

Underline links

Enable this if you want the links on web pages to be underlined.

Display server errors

Enable this if you want error messages to be generated by the host server.

Use Double Buffering

Enable this option to use offscreen contexts for image rendering, which makes for faster processing and less flicker.

UserAgent (netfront server only)

The UserAgent string.

Use 256 colors only

Enable this if you want to reduce the amount of image cache required to store images while running your monitor in a high-color or true-color mode.

Auto Load Images (vserver server only)

Enable this if you want images to be loaded when a page loads.

Fit into pane (netfront server only)

Toggle the NetFront Smart-Fit feature. This feature renders web content so that it fits into the width of the browser.

Disable Exception Dialog

Disable alerts from the JavaScript alert() function.

Enable WML (netfront server only)

Enable Wireless Markup Language (WML) support.

Print tab

Use the Print tab to configure the way Voyager prints pages. Select one of the four corners of the page icon to view the current header or footer format. You can:

• enter a new format, as listed under Formatting Codes in the dialog
• click Disable to disable that header or footer
• click Default to set the header or footer to the default setting.

Applications tab

Use the Applications tab to configure helper applications for MIME content on web pages. You can:

• click New Type to enter information about a new MIME type
• click Edit to edit the currently selected MIME type
• click Remove to delete the currently selected MIME type from the list.

Connecting to other systems

Photon supports the following methods for connecting between computers running Photon:

• Phditto -- a self-hosted utility that lets you view and interact with another Photon workspace in a network.
• Phindows -- a connectivity tool that lets you connect a Microsoft Windows platform to Photon and Photon applications on a remote Neutrino computer.

Phditto

The phditto utility lets you connect to a Photon session that's running on another computer. You can connect to an existing Photon session or start a new one. This utility lets you interact with the remote Photon session as though you were working directly on that node. In order to access the remote node using phditto, you must run phrelay on the remote machine.

You can end the phditto session by selecting Close from Phditto's window menu. To view this menu, right-click the phditto label in the Taskbar.

Phindows

Phindows ("Photon in Windows") is a connectivity tool that lets you use Windows platforms to connect to and interact with graphical Photon applications running on a remote Neutrino computer.

Configuring the Neutrino machine for TCP/IP use

If you're using TCP/IP, make sure the configuration is correct before you use Phindows:

• The remote Neutrino host must have TCP/IP installed and running.
• The remote host must also be running inetd, with the following items added to the TCP/IP configuration files:

  In /etc/inetd.conf, add the line:

  phrelay stream tcp nowait root /usr/bin/phrelay phrelay

  In /etc/services, add the line:

  phrelay 4868/tcp

  ---

  These lines are already present in the configuration files, but they're commented out. Just remove the number sign (#) to add these entries.

  ---

These two entries cause inetd to listen for incoming requests to establish a new Photon session. When a request is detected (from a remote Phindows client in our case), inetd automatically establishes a full TCP/IP connection and launches phrelay on that connection. Phindows is then fully connected to the local machine.

For more information about inetd, see the Utilities Reference.

Starting Phindows

To launch Phindows on your Windows machine, do one of the following:

• Click the Phindows icon, if you created one.
• Choose the Start-->Programs-->QNX Momentics-->Phindows menu entry.
• Run the C:\Program Files\phindows\phindows.exe program.

Phindows displays a Connect dialog where you can specify the type of connection (TCP/IP or direct-connect serial). Various connection options are available, but the defaults usually work well.

If you request a TCP/IP connection, you must also specify the Internet address of the Neutrino computer you're connecting to (e.g. 198.53.31.1). If the remote computer has been configured properly, you should see a Photon login prompt, at which point you're connected and running Photon.

If you request a serial connection, then you must specify the COM port (e.g. COM1 or COM2). If you don't specify a baud rate, Phindows uses the current Windows default settings. With a serial connection, Phindows initially acts as a simple text terminal that lets you type commands directly to the modem (e.g. ATDT1-613-591-0934). Once connected, log into Neutrino and then issue the command:

/usr/bin/phrelay

This command causes Phindows to drop out of text-terminal mode and begin acting as a Photon graphical terminal. A Photon login screen should appear at this point.

Additional options

You can use Phindows's command-line options to:

• set compression and data-caching options
• connect to a remote Photon session
• use a nonstandard color palette
• span a single Photon session across multiple screens
• share a Photon session with other users
• create a shortcut to a Photon application on a Windows desktop.

For more information, see the Phindows User's Guide.

Hotkeys and shortcuts

You can use many keyboard shortcuts and hotkeys to perform tasks quickly and easily. The following tables show shortcuts for using pterm, editing text fields in Photon applications, managing windows, working with the Photon workspace, and others.

pterm

The Photon terminal emulator is called pterm. It behaves like a character-device driver; see "The keyboard at a glance" in Using the Command Line.

If you're in typeover mode, and you press Enter, you return to insert mode.

The pterm program also supports the following shortcuts:

Text field

Window

The window manager, pwm, provides the following shortcuts:

Workspace

The window manager, pwm, provides the following shortcuts:

Photon skips any empty virtual consoles when you cycle through them.

The wmswitch process, which Photon starts automatically, provides these shortcuts:

Exiting Photon

If you want to exit Photon, you can press Ctrl-Alt-Shift-Backspace.

Before entering this command, make sure that no applications or utilities are running on your computer. If there are, files may be left open. Moreover, if you reboot when a critical update is in progress, the filesystem might need maintenance.

If you don't want anyone to be able to use this method to exit Photon, specify the -b option on the input driver for your system. For more information, see "Input drivers (devi-*)" in the Utilities Summary in the Utilities Reference.

Photon environment variables

Environment variables set options and determine the behavior of your system. You can use the command line to set environment variables that configure Photon, but the command depends on the shell that you're using. For ksh and esh, you can use the export command.

Here's a list of environment variable specific to Photon. For a general list of environment variables, see Commonly Used Environment Variables in the Utilities Reference.

ABLANG

A language code (e.g. en_CA for Canadian English) that a multilingual Photon application uses to determine what language to display.

For more information, see International Language Support in the Photon Programmer's Guide; for the currently supported codes, see /usr/photon/appbuilder/languages.def.

ABLPATH

A list of directories where you want a multilingual Photon application to search for translation files.

For more information, see International Language Support in the Photon Programmer's Guide, and ph in the Utilities Reference.

AB_RESOVRD

A path variable that lists directories to search for resource records for applications built with PhAB. See the Photon in Embedded Systems appendix of the Photon Programmer's Guide.

AUTOCONNECT

In order to run /etc/autoconnect, you must set this environment variable to 1. For more information, see /etc/autoconnect in the Utilities Reference.

DISPLAY

The name of the physical display on which to draw.

FLASHQUALITY

The resolution for voyager to use with Macromedia Flash.

IVE_HOME

Used by Java VM.

J9PLUGIN_ARGS

Arguments passed to Browser Java plugins.

PHEXIT_DISABLE

Set this environment variable to turn off the Photon Login dialog's Exit button so that users won't be able to exit to text mode. For more information, see phlogin2 and phlogin in the Utilities Reference.

PHFONT

The registered name of the font server (e.g. /dev/phfont).

For more information, see ph in the Utilities Reference.

PHFONT_USE_EXTERNAL

If this environment variable exists, io-graphics runs the font manager as a separate process (see phfont) instead of using phfont.so. You should set this environment variable for systems that have remote clients accessing font services on the host machine (e.g. phindows, phditto).

PHFONTMEM

The size of an area in shared memory to set up between the task and the Photon font server for returning text bitmaps (normally required only by graphics drivers). For more information, see PfAttach() in the Photon Library Reference.

PHFONTOPTS

Options to pass to the Photon font server. For more information, see phfont.

PHGFX

The full command that you want the ph script to use instead of the default commands to start the graphics driver.

PHINPUT

The full command that you want the ph script to use instead of the default commands to start the input driver.

PHINSTANCE

The number of times that Photon has been instantiated. For more information, see phlogin2 and phlogin in the Utilities Reference.

PHOTON

The name of the Photon device (usually /dev/photon). For more information, see ph in the Utilities Reference.

PHOTONOPTS

(Windows-hosted version only) Additional options you want to pass to the Photon server when it starts.

PHOTON_PATH

The name of the root directory containing Photon files (usually /usr/photon). For more information, see ph in the Utilities Reference.

PHWM

The name of the Window Manager to start when you start Photon. For more information, see ph in the Utilities Reference.

PHWMEXIT

If you set this environment variable, Photon disables the confirmation dialog when you exit Photon. For more information, see pwm in the Utilities Reference.

PHWMOPTS

Options you want to pass to the window manager when it starts. For more information, see pwm in the Utilities Reference.

PTERMPAL

The pathname of the palette file for pterm.

PTERMRC

The name of a local configuration file for pterm.

PWMOPTS

(Windows-hosted version only) Options you want to pass to the window manager when it starts. For more information, see pwm in the Utilities Reference.

PWM_PRINTSCRN_APP

The application to start when the Print Scrn key is pressed. The default is snapshot.

Troubleshooting

Here are some problems or questions that you might have concerning Photon:

How do I change the color scheme in Photon?

You can change the color of the title bars within Photon for any given state. To do this, choose Launch-->Configure-->Appearance, then select the Window tab. In this tab, you can choose one of the predefined schemes from the list, or you can set each window state (active and inactive) and the title color independently.

I've set an alias in my .profile, but it isn't set in my Photon terminals.

The shell doesn't export aliases. In Photon, the default pterm isn't started as a login shell and therefore doesn't read your /etc/profile and ~/.profile configuration files.

If you want an alias to be defined in all of your shells (inside or outside a Photon terminal), set the alias in your shell's startup file. For more information, see "ksh's startup file" in the Configuring Your Environment chapter in this guide.

Alternatively, you can use the -l option to run pterm as a login shell, which causes it to run .profile. If you want to, you can change the Terminal item on the shelf so that it executes pterm -l. To do this, right-click the shelf and choose Setup. Select the Terminal entry and change pterm to pterm -l.

You should also change the Desktop pop-up menu to match; edit $HOME/.ph/wm/wm.menu (or run phmenu) and add the -l option to the pterm entry.

I would like to bypass the login prompt when booting my computer into Photon. Is this possible?

Yes; for more information, see "rc.local" in the Controlling How Neutrino Starts chapter.

How can I change the language layout of my keyboard?

Choose the Localization item on the shelf. You can choose from several different keyboard configurations; see "International keyboards" in Using the Command Line.

How can I add files to the Helpviewer (such as help files for programs that I install, or new documents found on the web)? I noticed that the File menu doesn't let you bring up a file requester and look for a help file.

The Helpviewer looks for files with an extension of .toc in the /usr/help/product directory. Take a look at an existing .toc file as well as the Context-Sensitive Help chapter in the Photon Programmer's Guide.

To open an arbitrary file without creating the .toc files, use the Voyager browser instead of the helpviewer.

I tried to create new file associations with pfm, but they didn't work correctly. For example, based on the existing associations, I tried to associate .txt files with ped, but ped doesn't start.

Make sure you have /usr/photon/bin in your PATH environment variable, then do the following:

1. Start pfm.
2. Press F11 or select Associations from the Edit menu.
3. Click Add to add a new file association.
4. Enter these settings:
   • Pattern: *.txt
   • Open: ped
   • View: ped
   • Edit: ped
5. Choose Done to close the New Association Type dialog.
6. Choose Done to close the Associate dialog.

How can I disable the Ctrl-Alt-1, 2, ... keychords that allow console switching in Photon?

Place this line in your /etc/rc.d/rc.local file:

export PHWMOPTS="-S"
  

For more information, see pwm in the Utilities Reference.

If a mouse isn't connected to my computer, how do I shut down Photon?

You can press Ctrl-Alt-Shift-Backspace to shut down Photon. If it doesn't work, the computer may be locked up, in which case, you might have to press the reset button. To avoid using the reset button, run inetd, then telnet into the box and slay the processes that Photon is using.

How do I change the text and background colors of the terminal?

There's a -K option for pterm that lets you select the initial colors.

For example, pterm -K 17 sets the colors to blue text (1) on a light-gray background (7). You can also define the exact RGB values for all the 16 colors that pterm uses by creating a palette file. For more information, see pterm in the Utilities Reference.

When I change the language setting under Localization, nothing changes. Why?

This setting sets the ABLANG environment variable, which some applications use to determine what language they should use. Some applications may not support the language you've selected. Changing the setting typically doesn't affect applications that are running, just new ones.