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:
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>.
Prototypes have changed for:
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.
- ApCreateWidget()
- The widget is created as a child of the default parent, which is usually
the most recently created container.
To change the default parent, call
PtSetParentWidget().
- ApCreateWidgetFamily()
- The root of the widget family is created as a child of the default parent,
which is usually the most recently created container.
To change the default parent, call
PtSetParentWidget().
- 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.
- ApSetTranslation()
- An empty string, not a space, in the value of the ABLPATH
environment variable indicates the directory where the executable is
located.
Prototypes and header files have been corrected for:
The following have been added:
Prototypes have changed for:
Other changes:
- PfQueryFont()
- The description of the FontQueryInfo structure has
been corrected.
- PfQueryFonts()
- The description of the FontDetails structure has
been corrected.
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:
- PgDrawImage(), PgDrawImagemx()
- Instead of using this function, we recommend using a
PhImage_t
structure and calling
PgDrawPhImagemx().
- 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()
- Instead of using this function, we recommend using a
PhImage_t
structure and calling
PgDrawPhImagemx().
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.
New entries:
Prototypes have changed for:
Other changes are as follows:
- PhClipboardCopyString()
- The string must end with \0.
- PhEvent_t
- Descriptions of the bits for the processing_flags member
have been added.
- 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.
Use
PgDrawPhImagemx()
to draw a transparent image.
- PhMoveCursorRel()
- The coordinates passed to this routine are relative to the
current cursor position.
- PhQueryRids()
- Corrected the descriptions of the type and sense
arguments.
- 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.
Prototypes have changed for:
Other changes are as follows:
- PpPrintGetPC()
- The example has been corrected.
- PpPrintSetPC()
- GLOBAL_PC should be PRINTER_GLOBAL,
and LOCAL_PC should be PRINTER_LOCAL.
New:
Prototypes have changed for:
Deleted:
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.
- 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.
- PtMessageBox()
- If specified, the parent must be a window.
- 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.
- PtSetParentWidget()
- If the widget argument to this function is NULL
and you then call PtCreateWidget() with a NULL
parent argument, the new widget has no parent.
- 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.
|
- PtTimerArm()
- Any pending timers for a widget are removed automatically when the
widget is unrealized.
- PtWidgetIsClass()
- The class argument is of type
PtWidgetClassRef_t *.
The following functions have been added:
Prototypes have changed for:
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.
PX_TRANSPARENCY should be PX_TRANSPARENT.
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.
The example has been corrected; the format member of a
PhImage_t structure isn't used.
- PxTranslateFromUTF()
- 0 is no longer a valid value for the maxsrc argument.
- 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.
- wctolower()
- New.
We assume you already know the basics of using Photon. If not,
see the Photon
User's Guide.
![[Previous]](image-lib/prev.gif){kind=small}
![[Contents]](image-lib/contents.gif){kind=small}
![[Index]](image-lib/keyword_index.gif){kind=small}
![[Next]](image-lib/next.gif){kind=small}