About This Reference

For an overview of the changes to the software and docs, see "What's new in Photon 1.14 (as of September 27, 1999)."

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
• Ap-PhAB
• mbstr-Multibyte-Character
• Pf-Font Server
• Pg-Graphics
• Ph-Photon
• Pm-Memory
• Pp-Printing
• Pt-Widget Toolkit
• Px-Extended
• wc-Wide-Character
• Glossary

For functions that deal with specific widgets, see the Widget Reference. For functions that deal with creating widget classes, see Building Custom Widgets.

In general, the Photon libraries aren't thread-safe. In a multithreaded program, only the thread that called PtInit() is allowed to call Photon functions. The only exception is PtPulseDeliver() - you can use it in other threads to send notifications to the Photon thread.

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 1.14 (as of September 27, 1999)

Ap-PhAB

Prototypes have changed for:

• ApAppendTranslation()
• ApCopyWidget()
• ApCreateWidget()
• ApCreateWidgetFamily()
• ApDeleteWidget()
• ApError()
• ApGetBitmapRes()
• ApGetImageRes()
• ApGetTextRes()
• ApModifyItemText()
• ApOpenDBaseFile()
• ApSaveDBaseFile()
• ApSetTranslation()

Other changes are as follows:

ApAddClass()

The class_name_string argument is of type char const *.

This function keeps a pointer to the string pointed to by class_name_string; don't modify this string after calling ApAddClass().

ApCreateModule()

The return value has been corrected.

The widget argument is passed to the module's setup function as apinfo->widget.

ApGetBitmapRes()

The example for this function will work only if the old and new bitmaps have the same dimensions, number of colors/planes, and order of colors.

ApModifyItemText()

This function stores the address given by the new_text argument; it doesn't make a copy of the string pointed to by new_text.

This function returns 0 if the item number isn't valid.

ApModuleLocation()

The names of AB_LOC_BOT_LEFT and AB_LOC_BOT_RIGHT have been corrected.

ApOpenDBase(), ApOpenDBaseFile()

These functions typically open a picture module as a widget database, but they can also open window and dialog modules.

mbstr-Multibyte-Character

Prototypes and header files have been corrected for:

• mbstrblen()
• mbstrchr()
• mbstrlen()
• mbstrnchr()
• mbstrncmp()
• mbstrnlen()
• mbstrrchr()

Pf-Font Server

The following have been added:

• PfFractionalExtentText()
• PfFractionalRenderText()

Prototypes have changed for:

• PfExtentText()
• PfExtentComponents()
• PfRenderText()

Pg-Graphics

Prototypes have changed for:

• PgColorMatch()
• PgDrawArc()
• PgDrawBevelBox()
• PgDrawBeveled()
• PgDrawBezier(), PgDrawBeziermx()
• PgDrawBitmap(), PgDrawBitmapmx()
• PgDrawEllipse()
• PgDrawGrid()
• PgDrawImage(), PgDrawImagemx()
• PgDrawLine()
• PgDrawPhImagemx()
• PgDrawPixel()
• PgDrawPixelArray(), PgDrawPixelArraymx()
• PgDrawPolygon(), PgDrawPolygonmx()
• PgDrawRect()
• PgDrawRepBitmap(), PgDrawRepBitmapmx()
• PgDrawRepImage(), PgDrawRepImagemx()
• PgDrawRoundRect()
• PgDrawSpan(), PgDrawSpanmx()
• PgDrawString(), PgDrawStringmx()
• PgDrawText(), PgDrawTextmx(), PgDrawTextChars()
• PgDrawTextArea()
• PgDrawTImage(), PgDrawTImagemx()
• PgDrawTrend(), PgDrawTrendmx()
• PgExtentText()
• PgSetClipping()
• PgSetFont()
• PgSetMultiClip()
• PgSetPalette()
• PgSetStrokeDash()
• PgSetUserClip(), PgSetUserClipAbsolute()
• PgShmemAttach()
• PgShmemCreate()

Other changes are as follows:

PgDrawRepImage(), PgDrawRepImagemx()

Specify the image format, as described for PgDrawImage(), by ORing it into the flags argument.

PgDrawTextArea()

The flags for this function can include Pg_BACK_FILL and Pg_TEXT_WIDECHAR.

This function doesn't work in any context involving the render library, such as printing or Phindows. See the Caveats section.

PgDrawTImage(), PgDrawTImagemx()

The TransBPL argument is the number of bytes per line.

The leftmost pixel corresponds to the top bit of the first byte in the transparency mask.

PgSetClipping()

Don't call PgSetClipping() in a widget's draw function; use PtClipAdd() and PtClipRemove() instead. For more information, see the Building Custom Widgets guide.

PgSetPalette()

Pg_INDEXED_COLOR should be Pg_INDEX_COLOR.

PgSetPlaneMask()

This function works only on some 8-bit drivers.

PgSetStrokeWidth(), PgSetStrokeFWidth()

The minimum line width for PgSetStrokeFWidth() is one pixel.

We don't recommend using a line width greater than one pixel. Some graphics drivers might give unexpected results.

PgSetTextDither()

This function overrides the color defined by PgSetTextColor().

PgShmemDetach()

A shared memory object will persist until no other applications refer to it. Don't use the same name for another shared memory object, especially right after detaching the first one.

Ph-Photon

New entries:

• PhAddMergeTiles()
• PhClipTilings()
• PhCoalesceTiles()
• PhCopyTiles()
• PhDeTranslateTiles()
• PhFreeTiles() - replaces PhFreeTile().
• PhIntersectTilings()
• PhMergeTiles()
• PhRectsToTiles()
• PhSortTiles()
• PhTilesToRects()
• PhTranslateTiles()

Prototypes have changed for:

• PhAttach()
• PhChannelAttach()
• PhEventEmit()
• PhEventEmitmx()
• PhGetData()
• PhGetMsgSize()
• PhGetRects()
• PhInitDrag()
• PhKeyToMb()
• PhQuerySystemInfo()
• PhRegionChange()
• PhRegionDataFindType()
• PhRegionOpen()
• PhTo8859_1()

Other changes are as follows:

PhEventEmit()

The return codes have been explained more fully.

PhEventEmitmx()

The return codes have been explained more fully.

PhImage_t

The description of the image_tag member has been expanded.

Ph_RELEASE_IMAGE_ALL is a new flag that indicates that the image data, palette data, transparency mask bitmap, and the ghosting bitmap are all to be freed.

The mask_bpl member doesn't need to be a multiple of 4. The leftmost pixel of the image corresponds to the top bit of the first byte in the transparency and ghost masks.

PhMakeTransBitmap()

This function sets the image's Ph_RELEASE_TRANSPARENCY_MASK flag.

PhMoveCursorRel()

The coordinates passed to this routine are relative to the current cursor position.

PhReattach()

If the argument is NULL, this function returns a pointer to the current Photon control structure.

PhRegion_t

An overview of working with region data has been added.

PhRegionChange()

The data passed to this function is merged into the given region's data.

PhRegionDataHdr_t

A description has been added.

PhRegionOpen()

The example has been corrected. Specifically, the line:

if( event->type == Ph_EV_PTR_MOTION )
    

can never evaluate to true because Ph_EV_PTR_MOTION is defined as Ph_EV_PTR_MOTION_NOBUTTON | Ph_EV_PTR_MOTION_BUTTON. The line has been replaced by:

if( (event->type & Ph_EV_PTR_MOTION) != 0 )
    

PhWindowEvent_t

Ph_WM_STATE_ISICON has been deprecated.

Pp-Printing

Prototypes have changed for:

• PpLoadPrinter()
• PpPrintWidget()

Other changes are as follows:

PpPrintSetPC()

GLOBAL_PC should be PRINTER_GLOBAL, and LOCAL_PC should be PRINTER_LOCAL.

Pt-Widget toolkit

Prototypes have changed for:

• PtAddCallbacks()
• PtAddEventHandlers()
• PtAppAddSignalProc()
• PtAppInit()
• PtAppRemoveSignalProc()
• PtAskQuestion()
• PtCalcAbsPosition()
• PtContainerBox()
• PtContainerHit()
• PtCreateWidget()
• PtDamageExtent()
• PtDeTranslateRect()
• PtFileSelection()
• PtFindChildClass()
• PtFontSelection()
• PtForwardWindowEvent()
• PtForwardWindowTaskEvent()
• PtHit()
• PtInflateBalloon()
• PtInit()
• PtMessageBox()
• PtPrintSelection()
• PtRectIntersect()
• PtRectUnion()
• PtRemoveCallbacks()
• PtRemoveEventHandlers()
• PtSetAreaFromExtent()
• PtSetAreaFromWidgetCanvas()
• PtSetResources()
• PtSpawn()
• PtTranslateRect()
• PtWidgetHelpHit()

Other changes are as follows:

PtAppAddSignalProc()

You can add more than one function for a set of signals or set of intersecting signals. All handlers for a signal are called, but the order they're called in is unspecified.

PtAppAddWorkProc()

The example has been updated.

PtAppInit()

This function doesn't parse the command-line arguments.

PtAppRemoveSignalProc()

This function will remove any handlers for the given signals used internally by the libraries. You should use PtAppRemoveSignal() instead.

Pt_ARG()

New macro.

PtBkgdHandlerProcess()

It's safe to call PtBkgdHandlerProcess() in callbacks, work procedures, and input procedures, but not in a widget's Draw method or a PtRaw widget's drawing function.

PtContainerGiveFocus()

The Returns section has been expanded.

PtDeTranslateRect()

Returns a pointer to the rect argument.

PtForwardWindowTaskEvent()

The first argument is of type PhConnectId_t.

PtNextTopLevelWidget()

New function.

PtResizeEventMsg()

This function won't reduce the message buffer beyond a certain minimum size. This is so that the widget library will continue to function.

PtSetResources()

This function returns 0 if at least one of the given resources was applied to the widget. It returns -1 if the widget wasn't modified because it doesn't contain the given resources or the values of the resources were the same as those already stored in the widget.

---

A return code of 0 doesn't necessarily mean that all the resources were successfully set. The only way to be sure that a resource was set is to set it, then get it and compare the values.

---

PtWidgetHelpHit()

New function.

PtWidgetIsClass()

The class argument is of type PtWidgetClassRef_t *.

Px-Extended

The following functions have been added:

• PxTerminalBuildCharsets()
• PxTerminalLoadCharsets()
• PxTerminalSaveCharsets()

Prototypes have changed for:

• PxCRC()
• PxLoadImage()
• PxTranslateList()

Other changes are as follows:

PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort()

The value read by these functions can be signed. The characters after the sign determine the base:

Character(s):	Base:
0x or 0X	Hexadecimal
0	Octal
Other digits	Decimal

PxConfigWriteString()

You can use this function to write a comment in a configuration file.

PxLoadImage()

PX_USE_COLORS should be PX_USECOLORS.

The deallocation routine (the px_free member of the PxMethods_t structure) is called only if the image can't be loaded.

Descriptions of the PX_TRANSPARENCY flag and transparent member of the PxMethods_t structure have been added.

PxTranslateToUTF()

This function reads no more than maxsrc bytes. It no longer assumes that the src string is terminated by a \0 if maxsrc is zero.

wc-Wide-Character

wctolower()

New.

Assumptions

We assume you already know the basics of using Photon. If not, see the Photon User's Guide.