Using Gamma™ with the Photon microGUI®, Version 1.1

March 27, 2008

Gamma is the only dynamic language currently available for developing GUIs in the Photon environment. Gamma enhances Photon and PhAB with easy-to-use callbacks, expanded functionality for reusing widgets, and an object-oriented syntax.

Cogent software is source-code compatible among the Linux, QNX 6, and QNX 4 operating systems.
Go to the Cogent Web Site.
Copyright, trademark, and software license information.

Table of Contents

I. Programmers Manual

1. Introduction
1.1. Why Gamma and Photon?
1.2. Assumptions about the Reader
1.3. System Requirements
1.4. Cogent Product Integration
1.5. Where can I get help?

2. Classes
2.1. Explanation of Class Reference Pages
2.2. Specifying Widget Flags
2.2.1. Setting Flags
2.2.2. Testing Flags
2.2.3. Clearing Flags
2.2.4. Using Widget Method Calls
2.2.5. Using Bitmasks and cons
2.2.6. Using cons: a Summary
2.3. Specifying Colors

3. A Few Precautions

4. Building Applications - a Tutorial
4.1. Create a Window
4.2. Add an Exit Button
4.3. Add Functionality with Callbacks
4.4. Load a Window Created in PhAB
4.5. Read a Widget File and Create its Widgets
4.6. Read a Widget File and Assign its Widgets to a Class
4.7. Set, Test, and Clear Widget Flags
4.8. Read and Print a Widget File
4.9. Extract Certain Widgets
4.10. Select and Recreate Any Widget
4.11. Print a Widget Tree Summary

5. Integrating with Cogent Software
5.1. Callbacks and Cascade DataHub Points

6. Sample Code and Cool Stuff
6.1. Customizable Keypad
6.1.1. Create and Display Two Keypads
6.1.2. Sample Keypad Definition Files
6.1.3. The Keypad Class
6.2. Handling Keyboard Events
6.3. A CwGraph Rotating Cube
6.4. A CwMatrix Spreadsheet

A. GNU General Public License
B. GNU Lesser General Public License

II. Reference

I. PhAB Functions
PhabAttachWidgets - assigns widgets to a class as instance variables.
PhabChildren - a wrapper for the cdr function.
PhabCreateWidgets - creates widgets from existing definitions.
PhabLoad - reads, creates, names and realizes a widget hierarchy.
PhabLookupWidget - searches a widget hierarchy for a named widget.
PhabNameWidgets - assigns global variables to widget names.
PhabReadWidget - reads widgets (for internal use).
PhabReadWidgetFile - loads and accesses widget definitions.
PhabReadWidgets - reads widget files (for internal use).
PhabRoot - a wrapper for the car function.

II. Graphics Functions
ImageSubDivide - divides an image into columns and rows.
ImageThumbNail - resizes images by pixels.
ImageToLabel - makes a label from an image.
PgCMY - represents colors as combinations of cyan, magenta, and yellow.
PgGray - converts a gray level index from 8-bit to 24-bit color.
PgGrayValue - converts a color to a gray-scale equivalent.
PgHSV - represents color by hue, saturation, and brightness.
PgRedValue, PgGreenValue, PgBlueValue - indicate color strength.
PgRGB - represents colors as combinations of red, green, and blue.
PxConvolveImage - performs matrix-based convolutions on images.
PxCopyImage - copies an image.
PxGreyImage - converts colored images to grey.
PxLoadImage - loads image files.
PxReduceImage - resizes images by percentage.
PxSubImage - returns a sub-image of a passed image.
PxThresholdImage - converts grey-scale images to black and white.

III. Photon Functions
PhGetRects - gets rectangle sets.
PhEmitEvent - emits an event.
PhInitDrag - starts a drag.
PhMoveCursor - move the cursor to an absolute or relative position.
PhQueryRids - finds selected regions.
PhRegionChange - changes the definition of a region.
PhRegionQuery - gets information about a region.
PhWindowQueryVisible - finds the visible extent of a window.

IV. Widget Functions
PtAddResource - adds a resource.
PtAttachCallback - associates an action with a Photon event.
PtCollideWidget - checks for collisions between widgets.
PtContainerGiveFocus - gives focus to a widget.
PtContainerHold, PtContainerRelease - prevent/allow updating of container-widget contents.
PtDestroyWidget - deletes a widget.
PtEventHandler - is not yet implemented.
PtExtentWidget - forces a widget to calculate its extent.
PtFindDisjoint - finds the nearest disjoint parent widget.
PtFlush - immediately updates widgets.
PtFrameSize - sets the size of the window frame.
PtForwardWindowEvent - forwards a window event to the window manager.
PtGetAbsPosition - gives the absolute position of a widget.
PtGetParent - gives the class definition for a parent of a widget.
PtGetParentMember - not yet documented.
PtHit - searches a container for a widget.
PtHold, PtRelease - hold/release the issue of all Photon events to the Photon server.
PtInit - initializes the widget library.
PtInitDrag - starts a drag operation.
PtMainLoop - starts an infinite event loop.
PtModalStart, PtModalEnd - start and end modal processing.
PtProcessEvent - handles Photon events.
PtProtectCallbacks - protects code from callback errors.
PtQueryCallbacks - finds widget callback functions.
PtRawSetPos - is obsolete.
PtReParentWidget - changes parents of widgets.
PtRealizeWidget - initializes widgets.
PtRemoveCallback - removes a callback.
PtResourceName - finds a resource name from a resource number.
PtSetParentWidget - turns a widget into a parent widget.
PtSyncPhoton - flushes the current draw buffer.
PtTranslateRect - changes the position of PhRect class instances.
PtUnrealizeWidget - hides a widget.
PtUpdate - decrements the global hold count for widget repair.
PtWidgetChildren - finds the children of a widget.
PtWidgetParent - finds the parent of a widget.
PtWidgetToBack, PtWidgetToFront - moves a widget behind or in front of others.
TranslateRect - is obsolete. See PtTranslateRect.

V. Extended Functions
PxConfigClose - closes an open configuration file.
PxConfigDelete - delete entries and sections.
PxConfigForceEmptySection - creates an empty section in a configuration file.
PxConfigNextSection - moves to the next configuration file section.
PxConfigNextString - gets the next entry in the current section.
PxConfigOpen - Opens a configuration file.
PxConfigRead - read values from configuration files.
PxConfigSection - locates the start of a section.
PxConfigWrite - write values to configuration files.
PxHelpQuit - closes the helpviewer.
PxHelpTopic - opens the helpviewer to a topic page.
PxHelpTopicRoot - sets the helpviewer topic root.
PxHelpTopicTree - loads a topic tree into a helpviewer.
PxHelpUrl - displays helpviewer pages by URL address.
PxHelpUrlRoot - sets the default root for PxHelpUrl.
Usage - gives a QNX 4-style usage message during run-time.

VI. Widget Classes
CwGraph - A Cogent graph widget.
CwMatrix - A Cogent matrix widget.
PtArc - An elliptical arc.
PtBarGraph - A bar graph.
PtBasic - A parent class for basic widget resources.
PtBezier - A bezier curve.
PtBitmap - A bitmapped image.
PtBkgd - A background image, bitmap, or color-gradient.
PtButton - A push-button used to initiate a callback.
PtCalendar - A month-based calendar.
PtClock - A clock with analog, digital or LED-style format.
PtComboBox - A text field and a list of choices.
PtContainer - A parent class for container widget resources.
PtDBContainer - A double-buffered container that eliminates screen flicker.
PtDivider - A container with re-sizable rows or columns.
PtEllipse - An ellipse defined by a rectangular area.
PtFileSel - A tree-like widget used to select files and directories.
PtFolder - A file-folder style container.
PtFolderTab - A tab for accessing folder contents.
PtFontSel - is used to select font attributes.
PtGauge - A parent class for gauge widget resources.
PtGenList - A parent class for list and tree widget resources.
PtGenTree - A parent class for tree widget resources.
PtGraphic - A parent class for graphic widget resources.
PtGrid - A grid of horizontal and vertical lines.
PtGroup - groups widgets and manages their geometry.
PtHtml - An HTML viewer.
PtIcon - A container for a Photon Desktop Manager icon.
PtLabel - A label that displays text, bitmaps, or images.
PtLed - An LED-style data display.
PtLedBar - An LED display in bar format.
PtLedPanel - An LED display in panel format.
PtLine - A line defined by two points and an origin.
PtList - A scrollable list of items.
PtMenu - A pop-up or pull-down menu.
PtMenuBar - holds and manages menu buttons.
PtMenuButton - A button used to access menus.
PtMenuLabel - provides labels for menus.
PtMessage - A text message that appears in a pop-up window.
PtMeter - An arc-shaped real-time meter with indicator needle (in QNX 6).
PtMultiText - A text box that supports multiple lines and various text styles.
PtNumeric - A parent class for numeric widget resources.
PtNumericFloat - An entry box for floating-point values.
PtNumericInteger - An entry box for integer values.
PtOnOffButton - A button that can be set to ON or OFF.
PtPane - A container that facilitates anchoring and layout of other widgets.
PtPixel - A set of points.
PtPolygon - A set of points connected by lines.
PtRaw - A canvas for drawing Photon graphics primitives.
PtRect - A rectangle defined by two points.
PtRegion - A means to access and control regions of the interface.
PtScale - A marked scale.
PtScrollArea - A compact display of a large virtual area.
PtScrollbar - A sliding handle for navigating a scroll area.
PtSeparator - A line that separates menu items.
PtSlider - A sliding-scale input mechanism.
PtTerminal - A window that functions like a terminal.
PtText - A single-line or multi-line text entry/display field.
PtToggleButton - A button that toggles ON or OFF.
PtTree - An expanding/collapsing tree-style list of items.
PtTrend - A graph for displaying real-time trends (in QNX 6).
PtTty - A terminal that is attached to a device.
PtUpDown - A pair of buttons that increment and decrement a value.
PtWidget - The parent class of all widgets.
PtWindow - A window managed by the Photon Window Manager.
RtMeter - An arc-shaped real-time meter with indicator needle (in QNX 4).
RtProgress - A bar-style real-time progress indicator.
RtTrend - A graph for displaying real-time trends (in QNX 4).

VII. Callback Classes
CwMatrixCallback - matrix activity callback information.
PtBasicCallback - toggle status callback information.
PtCalendarSelectCallback - calendar selection callback information.
PtCallbackInfo - gives access to callback information.
PtClockTimeCallback - time change callback information.
PtContainerCallback - resize callback information.
PtDividerCallback - divider movement callback information.
PtFileSelCallback - file selection callback information.
PtFileSelBkgdCallback - directory item read callback information.
PtGenTreeInput - input callback information.
PtHotkeyCallback - hotkey callback information.
PtHtmlCallback - file loading callback information.
PtListCallback - item selection callback information.
PtListInput - text input callback information.
PtMeterCallback - needle movement callback information (in QNX 6).
PtNumericFloatCallback - float change callback information.
PtNumericIntegerCallback - integer change callback information.
PtOnOffButtonCallback - state change callback information.
PtScrollbarCallback - handle movement callback information.
PtSliderCallback - handle movement callback information.
PtTerminalFontChange - font change callback information.
PtTerminalInput - input callback information.
PtTerminalOptionChange - option change callback information.
PtTerminalScrlbkCb - scrollbar movement callback information.
PtTerminalSizeChange - size change callback information.
PtTextCallback - text change callback information.
PtTreeCallback - PtTree callback information.
PtTtyOutput - output callback information.
RtMeterCallback - needle movement callback information (in QNX 4).

VIII. Common Classes
CwMatrixCell - A cell of a CwMatrix.
PhArea - The position and size of a rectangular area.
PhBlitEvent - A bit block transformation (blit) event on a rectangular area.
PhBoundaryEvent - The event of leaving or entering an event region.
PhDim - The dimensions (height and width) of a widget.
PhDragEvent - The event of dragging an object.
PhDrawEvent - The event of drawing an object.
PhEvent - An event.
PhEventRegion - A region that emits or collects an event.
PhImage - Information about an image.
PhKeyEvent - The event of pressing a keyboard key.
PhPoint, PhLPoint - The (x,y) coordinates of a point.
PhPointerEvent - An event initiated by the pointer.
PhRect - A rectangular area defined by two points.
PhRegion - An area of the interface.
PhWindowEvent - An event related to a window.
PtCalendarDate - the day, month, and year.
PtEventData - data related to a variety of events.
PtFileSelItem - an item in a PtFileSel.
PtMultiTextAttributes - the attributes of PtMultiText text.
PtTreeItem - an item in a PtTree.


List of Tables

2.1. Using cons with widget flags.
2. Elements of a Widget Hierarchy
3. PxConfigWriteBool Format Options
4. PxConfigWriteChar Format Options
5. PxConfigWriteInt, -WriteLong, -WriteShort Format Options
6. PxConfigWriteString Format Options