Gamma/Photon

Using Gamma™ with the Photon microGUI®, Version 4.0

Jan 10, 2003

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.

With version 4.0, Cogent software now includes source-code compatibility among the QNX 4, QNX 6 and Linux operating systems, a reorganized and expanded API, and other improvements. Version 4.0 of Cogent's tools will not interoperate with version 3 or older. This documentation has been edited and reorganized to reflect those changes. For documentation of Cogent software version 3.x, please contact Cogent Real-Time Systems, Inc.

Go to the Cogent Web Site.

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. Where can I get help?

2. Classes

2.1. Explanation of Class Reference Pages
2.2. Specifying Widget Flags
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. Encapsulate Loading and Creating Widgets
4.11. Select and Recreate Any Widget
4.12. 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.2. Handling Keyboard Events
6.3. A CwGraph Rotating Cube
6.4. A CwMatrix Spreadsheet

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.
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.
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.
RtProgress -- A bar-style real-time progress indicator.
RtTrend -- A graph for displaying real-time trends.

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.
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.

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.

Index

Colophon

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

Prev	Home	Next
Colophon		Programmers Manual