HOOPS Publish Documentation

< Home

< Reference Manual

< File Formats

PROGRAMMING GUIDE

Contents

Programming with HOOPS Publish

Initializing and terminating a session

Handling Errors

Working with a PDF document

Inserting data on a page

Defining 3D

Populating page fields

Getting PDF nodes unique identifiers

Animation API

Inserting data on a page

Inserting a text line in a page

You can insert a text line in a page. The text should only be one line and cannot contain carriage return. You can parameterize the font for the text, chosen beyond one of the standard fonts in Adobe Reader. Standard fonts are four faces (normal, italic, bold, bold-italic) of three Latin text typefaces: Courier, Helvetica, and Times. These standard fonts are automatically handled by Adobe Reader and don’t require any font installation. The text string content is restricted by the use of these fonts. The supported character set is the "Latin Character Set" with the Standard Encoding described in the PDF reference. The text can be positioned anywhere on the page, specified by a position in page unit, from the bottom left of the page. To create a text line, use A3DPDFTextCreate, then use A3DPDFPageInsertText to insert it on the page.

A3DPDFTextData sTextData;
sTextData.m_iFontSize = 12;
sTextData.m_sColor.m_dRed = 0.4;
sTextData.m_sColor.m_dGreen = 0.4;
sTextData.m_sColor.m_dBlue = 0.4;
sTextData.m_pcTextString = "my text line";
A3DPDFText* pText = NULL;
iRet = A3DPDFTextCreate(pDoc, &sTextData, &pText);
iRet = A3DPDFPageInsertText(pPage, pText, iPosX, iPosY);

Inserting an image in a page

You can insert an image in a page. HOOPS Publish supports the most popular image formats (BMP, PNG, JPEG, GIF ...). The image can be positioned anywhere on the page, specified by a position in page unit, from the bottom left of the page. To create an image, use A3DPDFImageCreate, then use A3DPDFPageInsertImage to insert it on the page.

A3DPDFImageData sImageData;
sImageData.m_pcFileName = "c:\\temp\\myimage.jpg";
sImageData.m_iHeight = 480;
sImageData.m_iWidth = 640;
A3DPDFImage* pImage = NULL;
iRet = A3DPDFImageCreate(pDoc, &sImageData, &pImage);
iRet = A3DPDFPageInsertImage(pPage, pImage, iPosX, iPosY);

Inserting a link in a page

You can insert a link in a page. The link can be positioned anywhere on the page, specified by a position in page unit, from the bottom left of the page. To create a link, use A3DPDFLinkCreate, then use A3DPDFPageInsertLink to insert it on the page.

A3DPDFLinkData sLinkData;
char* jsactiv = "//activate page 2\n"
"var a3d = this.getAnnots3D( 1 )[0];\n"
"a3d.activated=true;\n"
"c3d = a3d.context3D;\n"
"c3d.runtime.setView(\"ALL\", true);\n";
sLinkData.m_eHighlightingMode = eHighlightingMode;
sLinkData.m_iBorderWidth = iBorderWidth;
sLinkData.m_sColor.m_dRed = 0.5;
sLinkData.m_sColor.m_dGreen = 0.0;
sLinkData.m_sColor.m_dBlue = 1.0;
sLinkData.m_pcJavascriptString = jsactiv;
A3DPDFLink* pLink = NULL;
iRet = A3DPDFLinkCreate(pDoc, &sLinkData, &pLink);
CHECK_RET;
// positioning the link in the page
sPos.m_iLeft = iLeft; // lower left x, from bottom left of the page
sPos.m_iBottom = iBottom; // lower left y, from bottom left of the page
sPos.m_iRight = iRight; // upper right x, from bottom left of the page
sPos.m_iTop = iTop; // upper right y, from bottom left of the page
iRet = A3DPDFPageInsertLink(pPage, pLink, &sPos);
CHECK_RET;

Inserting a table in a page

You can insert a table in a page. The table implementation uses an add-on to HOOPS Publish (TableToPDF) which is provided for free by Tech Soft 3D. The add-on is using components that are licensed under GNU LGPL terms. Consequently, the usage of tables using HOOPS Publish add-on requires our customer’s application to comply with LGPL requirements. TableToPDF can be downloaded at http://developer.techsoft3d.com/add-ons/tabletopdf/. The deployment process is simple and just requires to copy the provided DLLs in HOOPS Publish binaries folder.

Any number of tables can be positioned anywhere on the page. To create a table, use A3DPDFTableCreate, then use A3DPDFPageInsertTable to insert it on the page. The table insertion point is the top left corner of the table. The coordinate origin (0, 0) is the bottom left of the page. The unit is point.

More information is available on the Table Module.

A3DPDFTableData sTableData;
sTableData.m_pcHtmlTable = "&lt;table class=\"gridtable\"&gt; \
&lt;tr&gt; \
&lt;th&gt;Name&lt;/th&gt;&lt;th&gt;City&lt;/th&gt;&lt;th&gt;Age&lt;/th&gt; \
&lt;/tr&gt; \
&lt;tr&gt; \
&lt;td&gt;Bob&lt;/td&gt;&lt;td&gt;Seattle&lt;/td&gt;&lt;td&gt;35&lt;/td&gt; \
&lt;/tr&gt; \
&lt;tr&gt; \
&lt;td&gt;Sandy&lt;/td&gt;&lt;td&gt;New York&lt;/td&gt;&lt;td&gt;32&lt;/td&gt; \
&lt;/tr&gt; \
&lt;/table&gt;";
sTableData.m_pcHtmlStyle = "&lt;style type=\"text/css\"&gt; \
table.gridtable { \
font-family: helvetica; \
font-size:11pt; \
border-width: 1pt; \
border-collapse: collapse; \
} \
table.gridtable th { \
border-width: 1pt; \
border-style: solid; \
background-color: #dedede; \
padding: 8pt; \
} \
table.gridtable td { \
border-width: 1pt; \
border-style: solid; \
background-color: #ffffff; \
padding: 8pt; \
} \
&lt;/style&gt;";
A3DPDFTable* pTable = NULL;
// Warning, TableToPDF dll must be in the HOOPS Publish binary directory.
iRet = A3DPDFTableCreate(pDoc, &sTableData, &pTable);
iRet = A3DPDFPageInsertTable(pPage, pTable, iPosLeft, iPosTop);

Inserting widgets

HOOPS Publish supports text boxes, buttons, checkboxes, radio buttons, list boxes, drop down lists, and signature fields. They are all inserted similarly. The following example demonstrates how to insert a button.

Buttons

When clicked, a button will execute Javascript that you specify. Like all widgets, buttons are referenced by their name field, which is a string that you specify at creation time. Buttons can use text or images as the button label.

The first thing to do when inserting a button is to define an area on the page where you want it to be displayed. Remember that the coordinate system unit is points, and the origin is the bottom left corner of the page. The following code defines the button's area in the bottom left corner:

A3DPDFRectData pRectData;
pRectData.m_iTop = 100;
pRectData.m_iBottom = 0;
pRectData.m_iLeft = 0;
pRectData.m_iRight = 200;

Next, define the button's fields using A3DPDFButtonData. This structure is not stored and can be used to create additional buttons. The name field is required:

A3DPDFButtonData pButtonData;
pButtonData.m_pcName = "myButton"; // required!
pButtonData.m_pcLabel = "Hello Buttons";
pButtonData.m_pcFontName = "HeBo";
pButtonData.m_iFontSize = 12;
pButtonData.m_pcTooltip = "";
pButtonData.m_bHasBorder = true;
pButtonData.m_eLineStyleBorder = kA3DPDFSolid;
pButtonData.m_bHasFillColor = true;
pButtonData.m_sFillColor.m_dRed = 0.5;
pButtonData.m_sFillColor.m_dGreen = 0.5;
pButtonData.m_sFillColor.m_dBlue = 0.5;
pButtonData.m_eLayoutTextIcon = kA3DPDFLabelOnly;

Finally, the button is created and inserted. It is not shown here, but you should always remember to handle potential errors by checking return values for all A3D* functions:

A3DPDFButton* pButton;
A3DPDFButtonCreate(pDoc, &pButtonData, &pButton);
A3DPDFPageInsertButton(pPage, pButton, &pRectData);

Other widgets

Each widget type has its own data structure that is used for defining the widget. Many fields are common, but each widget type has a few special fields. For the widgets that accept user input, the input can only be retrieved using Javascript.

Follow the pattern above to insert other widgets - corresponding data structures are noted below:

Widget Data structure Creation function Insertion function Supporting function
Button A3DPDFButtonData A3DPDFButtonCreate A3DPDFPageInsertButton
Check box A3DPDFCheckBoxData A3DPDFCheckBoxCreate A3DPDFPageInsertCheckBox
Drop down list A3DPDFDropDownListData A3DPDFDropDownListCreate A3DPDFPageInsertDropDownList A3DPDFPageFieldListAddItem
List box A3DPDFListBoxData A3DPDFListBoxCreate A3DPDFPageInsertListBox A3DPDFPageFieldListAddItem
Signature field A3DPDFDigitalSignatureData A3DPDFDigitalSignatureCreate A3DPDFPageInsertDigitalSignature
Radio button A3DPDFRadioButtonData A3DPDFRadioButtonCreate A3DPDFPageInsertRadioButton
Text field A3DPDFTextFieldData A3DPDFTextFieldCreate A3DPDFPageInsertTextField

If you need more information on the widgets themselves, including their members and functions, consult Adobe's documentation.

Inserting a view carousel

HOOPS Publish v7.2+ facilitates the creation of a view carousel. This is a component which becomes useful when you have many defined views and would like a way for the end user to browse them. The carousel, outlined in red in the image below, is scrolled by a set of buttons that you have previously defined.

In the code sample below, A3DPDFDefineViewCarousel is used to create the carousel. uiNbViews and ppViews control which views will be inserted into the carousel. Set these to 0 and NULL, respectively, to insert all views. The last parameter can be used to provide preprocessed images to be used as posters for the buttons. All buttons, including the "up" and "down" buttons, but be previously defined and are referenced by their name.

For a complete example, see the samples/publish/publishsource/DemoFunctionalities.cpp sample included with the HOOPS Publish package. The function of interest is stWriteCarousel.

A3DPDFDefineViewCarousel(pDoc, pPage, p3DAnnot, pModelFile,
inbbuttons,
ppButtonsNames,
"scrollUpButton",
"scrollDownButton",
uiNbViews, // == 0? -> all
ppViews, // == NULL -> all views
NULL)); // == NULL -> images automatically created
1)); // number of views to scroll on each click

The view carousel renders button icons based on the views you specify. Then, it will apply the icons to the buttons automatically. As an example, let's say you have ten views, and would like to show four buttons at a time in the carousel. Only four (not ten) buttons need to be provided in ppButtonsNames. The carousel will alternate the button icons automatically as it is scrolled. Simply click on a button to activate that view.

If you want to scroll one page of views at a time, set the scroll step to the number of views in your carousel. For example, if you have a 2x2 carousel, set the scroll step to 4. To scroll half a page at a time, set the scroll step to 2.

Inserting a slide table

A slide table is an HTML table that can be scrolled using a vertical scroll bar or buttons. HOOPS Publish has a simplified interface for inserting slide tables. Slide tables are defined in HTML before being passed to A3DPDFDefineSlideTable. This function will implement the logic of populating the table rows as the user scrolls the table.

// example of inserting slide table which uses buttons
// see A3DPDFDefineSlideTable2 for function that uses scroll bar
A3DPDFDefineSlideTable(pDoc, // a reference to the PDF document you are creating
pPage, // the page on which this slide table will appear
450, 400, // the position, from bottom left of the page
pcHtmlSlideTableFrameDef, // table structure, defined in HTML
pcHtmlSlideTableFrameStyle, // table style, defined in HTML
"scrollUp", // name of previously defined button used to scroll up
"scrollDown", // name of previously defined button to scroll down
numRows, // number of table rows
numColumns, // number of table columns
pppTexts, // pointer to multidimensional array of table data
bHasHeader); // header is described in the table frame at first row and won't be scrolled

Example of button-based slide table end result:

Example of scroll bar slide table end result:

A complete example is demonstrated in samples/publish/publishsource/DemoFunctionalities.cpp.