Index

C/C++ Functions

pdImgAddPlus

DT_SLONG pdImgAddPlus(DT_PDDOC power_doc, DT_ID_SLONG obj, DT_SLONG page, DT_SLONG x, DT_SLONG y, DT_UBYTE status, DT_UBYTE attribs, DT_SLONG mask, DT_ID_SWORD fn_draw, const DT_TM3X3 transform)

Short Description: Add new image with an optional 3X3 transformation matrix

pdImgAdd

DT_SLONG pdImgAdd(DT_PDDOC power_doc, DT_ID_SLONG obj, DT_SLONG page, DT_SLONG x, DT_SLONG y, DT_UBYTE status, DT_UBYTE attribs, DT_SLONG mask, DT_ID_SWORD fn_draw, const DT_TM2X2 transform)

Short Description: Add new image with an optional 2x2 transformation matrix

The pdImgAddPlus (or pdImgAdd) function adds a PowerDoc image of the PowerDoc object obj at the top of the specified PowerDoc page and sets its X, Y coordinates, transformation matrix, visibility and other applicable parameters.

The return value of this function is the image's index in the Power Engine document. This index uniquely identifies the newly created PowerDoc image.

The only difference between pdImgAddPlus and pdImgAdd is that pdImgAddPlus uses a 3x3 transformation matrix while pdImgAdd uses a 2x2 transformation matrix. Therefore, pdImgAdd is more limited (i.e. this function cannot be used to apply a perspective transform to a PowerDoc image).

Parameters

ParameterDescription

power_doc

Handle of the associated Power Engine document.

obj

Index of the PowerDoc object to be associated with the newly created PowerDoc image.

page

The number of the page that will hold the PowerDoc image. Although not a requirement, it is recommended that this value be non-negative.

x

X coordinate of the PowerDoc image (or more precisely its origin point) on the page, in document units.

y

Y coordinate of the PowerDoc image (or more precisely its origin point) on the page, in document units.

status

At present, this parameter can have one of the following values:

status = 0 indicates a regular (non-selected) PowerDoc image.
status = 1 indicates a selected PowerDoc image.

The Power Engine API provides additional functions that operate on PowerDoc images depending on their status. For example, pdImgToTop, pdImgToBottom, pdImgMoveToPage, pdImgChangeAttribs, pdImgDelete and many other pdx functions use this value when selecting PowerDoc images.

When rendering the page using the library's default settings, selected PowerDoc images are visually marked with a small black square located at their origin point.

attribs

Represents additional image attributes. Currently, the following values are supported:

Bit 0 unset — indicates a visible PowerDoc image.
Bit 0 set — indicates a hidden PowerDoc image. Hidden images are not rendered.

Bit 2 unset — do not use fractional positioning for image origins.
Bit 2 set — use fractional positioning for image origins.

All other bits are reserved for future use and must be set to 0.

mask

The number of the masking page, i.e. the page whose alpha-channel will be used to mask the newly created PowerDoc image. For example, if the PowerDoc image represents a circle and the mask page contains many vertical stripes, then the resulting PowerDoc image will resemble a vertically striped circle.

If masking is not required, mask should be set to 0.

fn_draw

A numerical value of the rendering function to be associated with the newly created PowerDoc image. This can be a user-defined value or one of the following pre-defined PowerDoc values:

Basic PowerDoc Rendering Functions PowerDoc Rendering Functions To Render Form Controls
  • pdDrawSysGuideDashed (-3)
  • pdDrawSysGuide (-2)
  • pdDrawError (-1)
  • pdDrawNothing (0)
  • pdDrawTextLine (1)
  • pdDrawTextArc (2)
  • pdDrawTextArea (3)
  • pdDrawLine (4)
  • pdDrawEllipse (5)
  • pdDrawCircle (5)
  • pdDrawRect (6)
  • pdDrawTrueEllipse (7)
  • pdDrawTrueCircle (7)
  • pdDrawSlice (8)
  • pdDrawArc (9)
  • pdDrawRichTextArea (10)
  • pdDrawPattern (11)
  • pdDrawGrid (12)
  • pdDrawPoly (13)
  • pdDrawPolygon (13)
  • pdDrawShape (13)
  • pdDrawGradient (14)
  • pdDrawInverter (14)
  • pdDrawFastRect (14)
  • pdDrawImage (15)
  • pdDrawBitmap (15)
  • pdDrawChar (16)
  • pdDrawRichTextLine (17)
  • pdDrawLibraryPoly (18)
  • pdDrawLibraryPolygon (18)
  • pdDrawLibraryShape (18)
  • pdDrawRichTextArc (19)
  • pdDrawGlyph (20)
  • pdDrawGenericObject (21)
  • pdDrawGroup (22)
  • pdDrawDefault (22)
  • pdDrawPowerGlyph (23)
  • pdDrawPolyline (24)
  • pdDrawLibraryPolyline (25)
  • pdDrawTextDesign (26)
  • pdDrawRichTextDesign (27)
  • pdDrawTextPath (28)
  • pdDrawRichTextPath (29)
  • pdDrawLibraryImage (30)
  • pdDrawLibraryBitmap (30)
  • pdDrawBackground (31)
  • pdDraw3DModel (32)
  • pdDrawPolyImage (33)
  • fcDrawButton (10000)
  • fcDrawRadioButton (10001)
  • fcDrawCheckBox (10002)
  • fcDrawTextBox (10003)
  • fcDrawListBox (10004)
  • fcDrawHSlider (10005)
  • fcDrawVSlider (10006)
  • fcDrawRichTextBox (10007)
  • fcDrawRichButton (10008)
  • fcDrawRichListBox (10009)

transform

For pdImgAddPlus, this is a 3x3 transformation matrix. This matrix represents the 2D perspective (or projective) transform to apply to the newly created PowerDoc image. For more information, see the description of the DT_TM3X3 basic data type in this manual.

For pdImgAdd, this is a 2x2 transformation matrix. This matrix represents the top two rows and columns of the 2D perspective transform to apply to the newly created PowerDoc image. For more information, see the description of the DT_TM2X2 basic data type in this manual.

Return Value

The return value is the images's index in the Power Engine document. This number uniquely identifies the newly created PowerDoc image. For this reason, we sometimes refer to this index as the image's unique serial number.

If an error occurs, the return value will be a negative number.

Comments

To avoid unexpected results, rendering functions must be assigned to PowerDoc images in accordance with D-Type's Guidelines For Creating PowerDoc Objects.

Related Functions

pdImgDel

 

Index