About This Reference

Al ¦ Ap ¦ mbstr ¦ Pd ¦ Pf ¦ Pg ¦ Ph ¦ Pi ¦ Pm ¦ Pp ¦ Pt ¦ Px ¦ Rt ¦ wc

If you're familiar with earlier versions of Photon, you should read: "What's new in Photon for QNX 6.1" "What's new in Photon for QNX 6.0" to find out how the libraries have changed in this release.

The Photon Library Reference accompanies the Photon Development System and is intended for application developers. It describes the data types, structures, and functions that are defined in the Photon API.

This reference contains the following chapters:

• Summary of Entries
• Al -- PhAB Translation
• Ap -- PhAB
• mbstr -- Multibyte-Character
• Pd -- Draw Context
• Pf -- Font Server
• Pg -- Graphics
• Ph -- Photon
• Pi -- Images
• Pm -- Memory
• Pp -- Printing
• Pt -- Widget Toolkit
• Px -- Extended
• Rt -- Realtime
• wc -- Wide-Character
• Glossary

For functions that deal with specific widgets, see the Widget Reference. In general, the Photon libraries aren't thread-safe. For information on using Photon and threads, see "Threads" in the Lengthy Operations chapter of the Photon Programmer's Guide.

To use the datatypes and functions in an application:

• If you're using the Photon Application Builder (PhAB), the appropriate header files are automatically included in your application.
• If you aren't using PhAB but your application uses widgets, include <Pt.h>.
• If you aren't using PhAB or widgets, include <Ph.h>.

What's new in Photon for QNX 6.1

Patch A

New entries:

• PgDrawArrow()

New content in the docs

• PdSetOffscreenTranslation()
• PfFontBaseStem()
• PgDrawPhImage()
• PgDrawRepPhImage()
• PgGetRegion()
• PhMakeTransparent()
• PtAllowExit()
• PtPassword()
• PtPreventExit()
• PtPrintPropSelect()

Deprecated functions and data types

• PdOpenGLContextSetRid()
• PdOpenGLContextSwapBuffers()
• PgCreateGradient()
• PgGetGradientColor()
• PgGradientControl_t
• PgGradientLinear()
• PgGradientMakeImage()
• PgGradientPercent()
• PgGradientRotatePalette()

Other changes

PhWindowQueryVisible()

Ph_QUERY_CONSOLE and Ph_QUERY_WORKSPACE are new bits for the flags argument. Ph_QUERY_CONSOLE is the default value.

What's new in Photon for QNX 6.0

New functionality

Font names

An API for handling font names in an organized, portable way has been added. Previously, we recommended you address a font by the "stem name" supplied by the font manager (e.g. helv12). This approach is no longer recommended, since stem names aren't guaranteed to be static. This is especially true when new font technology is added to the Photon font subsystem. The new API provides an interface that eliminates the need to recode in the future. It includes:

• PfConvertFontID()
• PfFindFont()
• PfFontDescription()
• PfFontFlags()
• PfFontSize()
• PfFreeFont()

New content in the docs

Al -- PhAB Translation

These new functions support language and message databases:

• AlClearTranslation()
• AlCloseDBase()
• AlGetEntry()
• AlGetSize()
• AlOpenDBase()
• AlReadTranslation()
• AlSaveTranslation()
• AlSetEntry()

Ap -- PhAB

New:

• ApCloseMessageDB()
• ApCreateDBWidget()
• ApCreateDBWidgetFamily()
• ApDeleteDBWidget()
• ApGetDBWidgetInfo()
• ApGetMessage()
• ApLoadMessageDB()
• ApModalWait()

These functions have been renamed; you should use the new name, although applications that use the old name will still work:

• ApCopyWidget() -- now called ApCopyDBWidget()

Deprecated:

• ApBitmap_t
• ApDeleteWidget() -- you can use ApDeleteDBWidget() instead, but note that it deletes the given widget and its children.
• ApFreeBitmapRes()
• ApGetBitmapRes()

The prototype has changed for:

• ApCreateModule()

mbstr -- Multibyte-Character

New:

• mbstrichr()
• mbstrirchr()
• mbstrndup()
• mbstrnichr()

Pd -- Draw Context

New:

• PdCreateDirectContext()
• PdCreateOffscreenContext()
• PdDirectStart()
• PdDirectStop()
• PdDupOffscreenContext()
• PdGetDevices()
• PdGetOffscreenContextPtr()
• PdOffscreenContext_t
• PdReleaseDirectContext()
• PdSetTargetDevice()

Pf -- Font Server

New:

• PfConvertFontID()
• PfDecomposeStemToID()
• PfDynamicLoad()
• PfDynamicUnload()
• PfExtentFractTextCharPositions()
• PfExtentTextCharPositions()
• PfExtentTextToRect()
• PfExtentWideText()
• PfFindFont()
• PfFontDescription()
• PfFontFlags()
• PfFontSize()
• PfFreeFont()
• PfGenerateFontName()
• PfGetCacheStats()
• PfGetOutline()
• PfQueryFontInfo() -- replaces PfQueryFont()
• PfRenderWideText()
• PfTextWidthBytes()
• PfTextWidthChars()
• PfWideTextWidthBytes()
• PfWideTextWidthChars()

Deprecated:

• PfQueryFont() -- replaced by PfQueryFontInfo(), which returns a valid stem name when using a scalable font. The old function is still in the library, so applications that use it should still work.

Pg -- Graphics

New:

• PgAlphaOff()
• PgAlphaOn()
• PgBevelBox()
• PgCalcColorContrast()
• PgChromaOff()
• PgChromaOn()
• PgConfigScalerChannel(),
• PgContextBlit()
• PgContextBlitArea()
• PgContrastBevelBox()
• PgCreateVideoChannel(),
• PgDestroyVideoChannel(),
• PgDrawGradient()
• PgDrawGradientBevelBox()
• PgDrawMultiTextArea()
• PgDrawPhImageRectmx()
• PgDrawRepPhImagemx()
• PgExtentMultiText()
• PgGetGraphicsHWCaps()
• PgGetOverlayChromaColor(),
• PgGetScalerCapabilities(),
• PgGetVideoMode()
• PgGetVideoModeInfo()
• PgGetVideoModeList()
• PgNextVideoFrame(),
• PgScalerCaps_t,
• PgScalerProps_t,
• PgReadScreen()
• PgReadScreenSize()
• PgSetAlpha()
• PgSetAlphaBlend()
• PgSetChroma()
• PgSetDPMSMode()
• PgSetVideoMode()
• PgSwapDisplay()
• PgVideoChannel_t
• PgWaitDrawComplete()
• PgWaitHWIdle()
• PgWaitVSync()

Other new features:

PgSetDrawMode()

New drawing modes.

Ph -- Photon

New:

• PhAllocPackType()
• PhAreaToRect()
• PhCreateImage()
• PhCreateTransportCtrl()
• PhDCCreate()
• PhDCRelease()
• PhDeTranslateRect()
• PhEmit() -- similar to PhEventEmit(), but with a cleaner API
• PhEmitmx() -- similar to PhEventEmitmx(), but with a cleaner API
• PhFindTransportType()
• PhFreeTransportType()
• PhGetAllTransportHdrs()
• PhGetNextInlineData()
• PhGetNextTransportHdr()
• PhGetTransportHdr()
• PhGetTransportVectors()
• PhInputGroup()
• PhLinkTransportData()
• PhLocateTransHdr()
• PhMallocUnpack()
• PhPackEntry()
• PhPackType()
• PhRectIntersect() -- replaces PtRectIntersect()
• PhRectToArea()
• PhRectUnion() -- replaces PtRectUnion()
• PhRegionGetData()
• PhRegisterTransportType()
• PhReleaseTransportCtrl()
• PhReleaseTransportHdrs()
• PhTranslateRect() -- replaces PtTranslateRect()
• PhTransportFindLink()
• PhTransportCtrl_t
• PhTransportLink_t
• PhTransportRegEntry_t
• PhTransportType()
• PhUnlinkTransportHdr()
• PhUnpack()

Other changes:

PhEvent_t

Ph_EV_BUT_RELEASE events have a new subtype, Ph_EV_RELEASE_OUTBOUND.

PhInitDrag()

The prototype has changed; the ptrpos and cursor arguments have been added.

PhMakeTransBitmap()

This function now supports all image types currently supported by Photon. The meaning of the trans_color argument depends on the image type.

Pi -- Images

These new functions support image operations:

• PiCropImage()
• PiDuplicateImage()
• PiFlipImage()
• PiGetPixel()
• PiGetPixelFromData()
• PiGetPixelRGB()
• PiSetPixel()
• PiSetPixelInData()

Pp -- Printing

New functions:

• PpContinueJob() -- replaces PpPrintStart()
• PpCreatePC() -- replaces PpPrintCreatePC()
• PpEndJob() -- replaces PpPrintClose()
• PpFreePrinterList()
• PpGetCanvas()
• PpGetPC() -- replaces PpPrintGetPC()
• PpLoadDefaultPrinter()
• PpLoadPrinterList()
• PpReleasePC() -- replaces PpPrintReleasePC()
• PpSetCanvas()
• PpSetPC() -- replaces PpPrintSetPC()
• PpStartJob() -- replaces PpPrintOpen()
• PpSuspendJob() -- replaces PpPrintStop()

Other changes:

PpPrintWidget()

You no longer need to call PtFlush() after calling this function.

Pt -- Widget toolkit

New:

• PtAddClassStyle()
• PtAddFilterCallback()
• PtAddFilterCallbacks()
• PtAddResponseType()
• PtAlert()
• PtAppSetFdMode()
• PtBlit()
• PtBlockAllWindows()
• PtBlockWindow()
• PtCalcCanvas()
• PtCalcSurface()
• PtCalcSurfaceByAction()
• PtCalcSurfaceById()
• PtCancelDnd()
• PtCheckSurfaces()
• PtClippedBlit()
• PtCondTimedWait()
• PtCondWait()
• PtConnectionAddEventHandlers()
• PtConnectionAddMsgHandlers()
• PtConnectionClientGetUserData()
• PtConnectionClientSetError()
• PtConnectionClientSetUserData()
• PtConnectionFindId()
• PtConnectionFlush()
• PtConnectionFindName()
• PtConnectionNotify()
• PtConnectionReply(), PtConnectionReplymx()
• PtConnectionResizeEventBuffer()
• PtConnectionSend(), PtConnectionSendmx()
• PtConnectionServerDestroy()
• PtConnectionServerGetUserData()
• PtConnectionServerSetError()
• PtConnectionServerSetUserData()
• PtConnectionTmpName()
• PtConnectionWaitForId()
• PtConnectionWaitForName()
• PtConnectorCreate()
• PtConnectorDestroy()
• PtConnectorGetId()
• PtCRC() -- replaces PxCRC()
• PtCRCValue()
• PtCreateActionSurface()
• PtCreateSurface()
• PtCreateTransportCtrl()
• PtDamageSurface(), PtDamageSurfaceById()
• PtDamageSurfaceByAction()
• PtDestroyAllSurfaces()
• PtDestroySurface()
• PtDestroySurfaceById()
• PtDisableSurface(), PtDisableSurfaceById()
• PtDisableSurfaceByAction()
• PtDndFetch_t
• PtDndSelect()
• PtEnableSurface(), PtEnableSurfaceById()
• PtEnableSurfaceByAction()
• PtEnter()
• PtExit()
• PtFindFocusNextFrom()
• PtFindFocusPrevFrom()
• PtFindSurface()
• PtFindSurfaceByAction()
• PtGetResource()
• PtGiveFocus()
• PtHelpQuit() -- replaces PxHelpQuit()
• PtHelpSearch() -- replaces PxHelpSearch()
• PtHelpTopic() -- replaces PxHelpTopic()
• PtHelpTopicRoot() -- replaces PxHelpTopicRoot()
• PtHelpTopicTree() -- replaces PxHelpTopicTree()
• PtHelpUrl() -- replaces PxHelpUrl()
• PtHelpUrlRoot() -- replaces PxHelpUrlRoot()
• PtHideSurface(), PtHideSurfaceById()
• PtHideSurfaceByAction()
• PtInitDnd()
• PtInsertSurface(), PtInsertSurfaceById()
• PtLeave()
• PtMakeModal()
• PtModalBlock()
• PtModalUnblock()
• PtNotice()
• PtPrintSelect()
• PtPrompt()
• PtPulseArm()
• PtQuitMainLoop()
• PtReleaseTransportCtrl()
• PtRemoveFilterCallback()
• PtRemoveFilterCallbacks()
• PtSetAreaFromCanvas()
• PtSetResource()
• PtShowSurface(), PtShowSurfaceById()
• PtShowSurfaceByAction()
• PtSurfaceActionId()
• PtSurfaceAddData(), PtSurfaceAddDataById()
• PtSurfaceBrotherBehind()
• PtSurfaceBrotherInFront()
• PtSurfaceCalcBoundingBox(), PtSurfaceCalcBoundingBoxById()
• PtSurfaceExtent(), PtSurfaceExtentById()
• PtSurfaceGetData(), PtSurfaceGetDataById()
• PtSurfaceHit()
• PtSurfaceId()
• PtSurfaceInBack()
• PtSurfaceInFront()
• PtSurfaceIsDisabled()
• PtSurfaceIsEnabled()
• PtSurfaceIsHidden()
• PtSurfaceIsShown()
• PtSurfaceRect(), PtSurfaceRectById()
• PtSurfaceRemoveData(), PtSurfaceRemoveDataById()
• PtSurfaceTestPoint()
• PtSurfaceToBack(), PtSurfaceToBackById()
• PtSurfaceToFront(), PtSurfaceToFrontById()
• PtTransportCtrl_t
• PtTransportRequestable()
• PtTransportType()
• PtUnblockWindows()
• PtWidgetActiveSurface()
• PtWidgetMinimumSize()
• PtWidgetPreferredSize()
• PtWindowFrameSize()

Deprecated:

• PtAskQuestion()
• PtBasicWidgetCanvas(), PtLabelWidgetCanvas(), PtWidgetCanvas() -- use PtCalcCanvas() instead.
• PtDeTranslateRect() -- use PhDeTranslateRect()
• PtFrameSize() -- use PtWindowFrameSize()
• PtPulseArmFd(), PtPulseArmPid() -- use PtPulseArm() instead.
• PtPulseDeliver() -- use MsgDeliverEvent() instead (see the QNX 6 Library Reference).
• PtPulseDisarm() -- you don't need this under version 6 of the QNX RTOS.
• PtSetAreaFromExtent() -- use PhRectToArea()
• PtSetAreaFromWidgetCanvas() -- use PtSetAreaFromCanvas()
• PtSyncPhoton() -- use PtExit() instead.
• PtTranslateRect() -- use PhTranslateRect()

These functions have been renamed; you should use the new name, although applications that use the old name will still work:

• PtReParentWidget() -- now called PtReparentWidget()

Other changes:

PtCreateWidget()

The parent argument has changed. It can now be a pointer to the parent widget or one of:

• Pt_DEFAULT_PARENT -- use the default parent, which is the most recently created container.
• Pt_NO_PARENT

PtFileSelection()

This function can select directories as well as files. Enable directory selection with the Pt_FSDIALOG_SELECT_DIRS flag. Existing directories can be selected with btn1 (the Open button).

PtFileSelection() can create and delete directories and delete files. You can create new directories at any time by pressing the New button. When the PtFileSel widget has focus, two new hotkeys are activated: the Insert key creates a new directory just like the New Directory button, and the Delete key removes the currently selected item.

The info structure has the following new members:

• user_data
• confirm_display
• confirm_selection
• new_directory

New flags:

• Pt_FSR_NO_FCHECK -- replaces Pt_FSDIALOG_NO_FCHECK
• Pt_FSR_NO_FSPEC -- replaces Pt_FSDIALOG_NO_FSPEC
• Pt_FSR_NO_UP_BUTTON -- replaces Pt_FSDIALOG_NO_UP_BUTTON
• Pt_FSR_NO_NEW
• Pt_FSR_NO_NEW_BUTTON
• Pt_FSR_NO_SELECT_FILES
• Pt_FSR_SELECT_DIRS
• Pt_FSR_CREATE_PATH
• Pt_FSR_NO_CONFIRM_CREATE_PATH
• Pt_FSR_NO_DELETE
• Pt_FSR_NO_CONFIRM_DELETE
• Pt_FSR_RECURSIVE_DELETE
• Pt_FSR_CONFIRM_EXISTING

PtModalEnd()

The prototype has changed; this function no longer takes as an argument the value returned by PtModalStart().

PtModalStart()

No longer returns anything.

PtRectIntersect()

Replaced by PhRectIntersect() --

PtRectUnion()

Replaced by PhRectUnion() --

Px -- Extended

PxCRC()

Replaced by PtCRC().

PxHelpQuit()

Replaced by PtHelpQuit()

PxHelpSearch()

Replaced by PtHelpSearch()

PxHelpTopic()

Replaced by PtHelpTopic()

PxHelpTopicRoot()

Replaced by PtHelpTopicRoot()

PxHelpTopicTree()

Replaced by PtHelpTopicTree()

PxHelpUrl()

Replaced by PtHelpUrl()

PxHelpUrlRoot()

Replaced by PtHelpUrlRoot()

PxLoadImage()

If PX_TRANSPARENT is set in the flags member of the PxMethods_t structure, PxLoadImage() makes the image transparent, using the detected transparent color and the image's chroma scheme. There's no need to set the transparent member of this structure -- it's deprecated.

PxTranslateUnknown()

Control how unknown encodings are handled

You no longer need to include <photon/PxHelp.h> when using the help functions.

Rt -- Realtime

New:

• RtTimerCreate()
• RtTimerDelete()
• RtTimerGetTime()
• RtTimerSetTime()

Corrections

Pg -- Graphics

PgDrawImage(), PgDrawImagemx()

Instead of using this function, we recommend using a PhImage_t structure and calling PgDrawPhImagemx().

PgDrawTImage(), PgDrawTImagemx()

Instead of using this function, we recommend using a PhImage_t structure and calling PgDrawPhImagemx().

Ph -- Photon

PhMakeTransBitmap()

Use PgDrawPhImagemx() to draw a transparent image.