Data Model Module
Types
Fields
Functions
Detailed Description
- group a3d_pdf_datamodel_module
(HOOPS Publish Advanced) Module to modelize data tables and interactivity.
This module describes the functions and structures that allow you to define tables, relationships and widgets on a PDF page, as well as describing interactivity between widgets.
The process to define a data model binding is as follows:
Tables and Relationships must be created with A3DPDFDataTableCreate and A3DPDFDataRelationshipCreate.
The widgets are primarily created by other API functions, or with Acrobat Forms. Widgets can be Acrobat fields (text field, button, list), or a high level widget (ScrollTable, ViewCarousel …)
Use A3DPDFXXXBindToTable functions to bind a widget to a data table.
Use A3DPDFWidgetSetTargetBehaviour functions to define the interactivity between widgets.
Init states are defined as follows (also used when unselecting a widget): . Text fields are empty . List fields display the whole data table . 3D annot is defined in the PRC
Type Documentation
-
enum A3DPDFEWidgetTargetBehaviour
Types of behaviours for a widget when targetted from another widget.
- Version
9.2
Values:
-
enumerator kA3DPDFDataIsolate
Isolate the rows.
-
enumerator kA3DPDFDataHighlight
Highlight the rows.
-
enumerator kA3DPDFDataSelect
Select the rows.
-
enumerator kA3DPDFDataIsolateAndSelect
Isolate the rows, then selects the first item.
Function Documentation
-
A3DStatus A3DPDFPageGetDataFilterFromDropDownListField(A3DPDFPage *pPage, const A3DUTF8Char *pcFieldId, A3DPDFDataFilter **ppDataFilter)
Function to get a widget filter object from an existing drop down field.
Filter widgets are specific. A filter widget enables the user to apply a filter to a table related to the table bound to this widget. Hence, the table bound to the filter widget should have a relationship with another table on which apply the filter. Each entry of the filter widget isolate a set fo data onto the related table. There’s a specific entry which might be defined as first row to disable all filtering (hence, displaying all data).
See also
- Version
10.0
- Parameters:
pPage – [in] The Page object on which is the field.
pcFieldId – [in] Unique name for the drop down field.
ppDataFilter – [out] The A3DPDFDataFilter object created.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDF3DAnnotGet3DNodeScene(A3DPDF3DAnnot *p3DAnnot, A3DPDF3DNodeScene **pp3DAnnotUIListNodes)
Function to get a widget object for the list of 3D nodes from an existing 3D annot.
- Version
10.0
- Parameters:
p3DAnnot – [in] The Annot 3D previously created with A3DPDF3DAnnotCreate.
pp3DAnnotUIListNodes – [out] The widget object created.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDF3DAnnotGet3DViewList(A3DPDF3DAnnot *p3DAnnot, A3DPDF3DViewList **pp3DAnnotUIListViews)
Function to get a widget object for the list of 3D views from an existing 3D annot list views UI.
- Version
10.0
- Parameters:
p3DAnnot – [in] The Annot 3D previously created with A3DPDF3DAnnotCreate.
pp3DAnnotUIListViews – [out] The widget object created.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFWidgetBindColumnsActions(A3DPDFWidget *pWidget, const A3DInt32 iSizeMap, const A3DInt32 *piMapColumns)
Function to define some custom actions on row widgets which are not visible on the widget and were not mapped with a BindToTable function. This function should be called in addition to another BindToTable function. The columns associated must define custom actions, formatted as a json string with a property named ‘actionrowcustomjs’and a property value defining javascript code. Note that double quotes should be prefixed with a ‘', as well as backslashes. For example, the content of the data table cell could be: “{ "actionrowcustomjs" : "console.println(\"here is an action to run\");" }” Several actions can be defined , they will be executed in the order of the map.
- Version
24.1
- Parameters:
pWidget – [in] The widget object to bind to a table.
iSizeMap – [in] Size of the following array.
piMapColumns – [in] Array of indexes (starting from 0) of column mapped to this widget.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFTextFieldBindToTable(A3DPDFTextField *pTextField, A3DPDFDataTable *pDataTable, const A3DInt32 iMappedColumn)
Function to bind a widget text field to a table.
- Version
10.0
- Parameters:
pTextField – [in] The Widget text field to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
iMappedColumn – [in] index (starting from 0) of column mapped to this widget.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFScrollTableBindToTable(A3DPDFScrollTable *pScrollTable, A3DPDFDataTable *pDataTable, const A3DInt32 iSizeMap, const A3DInt32 *piMapColumns)
Function to bind a widget scroll table to a table.
- Version
10.0
- Parameters:
pScrollTable – [in] The scroll table object to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
iSizeMap – [in] Size of the following array.
piMapColumns – [in] Array of indexes (starting from 0) of column mapped to this widget.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFListBoxBindToTable(A3DPDFListBox *pListBox, A3DPDFDataTable *pDataTable, const A3DInt32 iMappedColumn)
Function to bind a widget list box to a table.
- Version
10.0
- Parameters:
pListBox – [in] The widget list box to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
iMappedColumn – [in] index (starting from 0) of column mapped to this widget.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFDropDownListBindToTable(A3DPDFDropDownList *pDropDownList, A3DPDFDataTable *pDataTable, const A3DInt32 iMappedColumn)
Function to bind a widget dropdown list to a table.
- Version
10.0
- Parameters:
pDropDownList – [in] The widget dropdown list to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
iMappedColumn – [in] index (starting from 0) of column mapped to this widget.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDF3DNodeSceneBindToTable(A3DPDF3DNodeScene *p3DAnnotUIListNodes, A3DPDFDataTable *pDataTable, const A3DInt32 iMappedColumn)
Function to bind a widget object for the list of 3D nodes, to a table.
- Version
10.0
- Parameters:
p3DAnnotUIListNodes – [in] The Widget object to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
iMappedColumn – [in] index (starting from 0) of column mapped to this widget.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDF3DViewListBindToTable(A3DPDF3DViewList *p3DAnnotUIListViews, A3DPDFDataTable3DViews *pDataTable)
Function to bind a widget object for the list of 3D views, to a table.
- Version
10.0
- Parameters:
p3DAnnotUIListViews – [in] The Widget object to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDF3DViewCarouselBindToTable(A3DPDF3DViewCarousel *p3DViewCarousel, A3DPDFDataTable3DViews *pDataTable)
Function to bind a widget view carousel to a table.
- Version
10.0
- Parameters:
p3DViewCarousel – [in] The view carousel object to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFDataFilterWidgetBindToTable(A3DPDFDataFilter *pDataFilter, A3DPDFDataTable *pDataTable, const A3DInt32 iSizeMap, const A3DInt32 *piMapColumns, const A3DUTF8Char *pcValueNoFilterApplied)
Function to bind a filter widget to a table.
- Version
10.0
- Parameters:
pDataFilter – [in] The filter widget object to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
iSizeMap – [in] Size of the following array
piMapColumns – [in] Array of indexes (starting from 0) of column mapped to this widget.
pcValueNoFilterApplied – [in] If the filter widget is a drop down list, pcNoFilterApplied is the value to add as first row of the widget. If pcValueNoFilterApplied is specified, selecting the first row of the widget disables the filters. If pcValueNoFilterApplied is not specified, a filter is always applied (there is no ‘nofilter’ state ; default is first row).
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFButtonBindToTable(A3DPDFButton *pButton, A3DPDFDataTable *pDataTable, const A3DInt32 iSizeMap, const A3DInt32 *piMapColumns)
Function to bind a widget button to a table.
The button can be bound to two columns types: index 0 is for the icon id for button. index 1 is optional and is for the label of the button.
- Version
10.2
- Parameters:
pButton – [in] The Widget text field to bind to a table.
pDataTable – [in] The Data Table object to bind the widget to.
iSizeMap – [in] Size of the following array.
piMapColumns – [in] Array of indexes (starting from 0) of column mapped to this widget.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFWidgetSetTargetBehaviour(A3DPDFWidget *pWidgetSource, A3DPDFWidget *pWidgetTarget, A3DPDFEWidgetTargetBehaviour eBehaviourOnTarget)
Function to define an interaction between two widgets.
An interaction acts as follows: if the user clicks on the widget source, then a table joint is calculated using the relationship between the table associated from pWidgetSource to the table associated to pWidgetTarget. The result of the joint is a set of indexes in the table related to pWidgetTarget. The widget target is ultimately filled from this result set, depending on the eBehaviourOnTarget value:
kA3DPDFDataIsolate: only the rows in result set are displayed in the widget.
kA3DPDFDataHighlight: the widget displays all the rows from its binded table, but only the rows in result set are highlighted.
kA3DPDFDataSelect: for this, the result set must contain only one value. Then in this case, the target widget acts as if the user selected the row indexed by this value.
kA3DPDFDataIsolateAndSelect: the widget is populated as with kA3DPDFDataIsolate. Then, it acts as if the user selected the first item. This behaviour is valid only for list widgets.
A widget can be specifed as target without a source, to be automatically populated whenever the table bound is selected, whatever source widget triggered this selection. For this, use A3DPDFWidgetSetTargetBehaviour(NULL, WidgetTarget);
A widget that has to be populated at init time (when the file is opened) should have a NULL source specified, and the table bound should be set for init time with
A3DPDFDataTableSetInitIndex.
A widget not connected to any other widget have automatically the source specified to NULL, and then is automatically populated with all rows of the data table when the file is opened.
A widget connected to a source widget with kA3DPDFDataIsolate behaviour always remains empty at init time.- Version
10.0
- Parameters:
pWidgetSource – [in] Widget source of interaction. Can be NULL to automatically populate the target widget at init time
pWidgetTarget – [in] Widget to be refreshed.
eBehaviourOnTarget – [in] Values allowed for this kind of widget target: see A3DPDFEWidgetTargetBehaviour
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDF3DAnnotActivatePMICrossHighlightAndSelect(A3DPDF3DAnnot *p3DAnnot, A3DBool bActivatePMICrossHighlightAndSelect)
Function to activate the PMI cross highlight and select behaviour. With this, some JavaScript code is generated so that when the user clicks on a markup, the associated surface is highlighted, and then the solid node containing the surface is selected. Only works with Acrobat 11 and later.
- Version
10.1
Warning
If this behaviour is activated, when the node is selected, the PMI originally selected is unselected. If datamodel connection is linked to a PMI node, the connection will be resetted as if the PMI node is unselected.
- Parameters:
p3DAnnot – [in] The Annot 3D to work on.
bActivatePMICrossHighlightAndSelect – [in] If true, activate the PMI cross highlight and select behaviour.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDF3DViewListEnableViewTransitions(A3DPDF3DViewList *p3DAnnotUIListViews, A3DBool bTransitionActive)
Function to define if the transition between views must be animated or not. This is applicable to widgets implied with datamodel, and only with activation by datamodel. Implied widgets are A3DPDF3DViewList, and A3DPDF3DViewCarousel as the carousel widget must be in relationship with the view list widget to perform the view activation.
- Version
13.1
- Parameters:
p3DAnnotUIListViews – [in] The widget to interact with 3D views.
bTransitionActive – [in] Defines if the transition between views must be animated or not. If true, an animation is played to transition to the view. The animation is automatically calculated by Acrobat depending on camera settings. If false, the view is activated without animation. By default, i.e. if this function is not called, the value is TRUE: all view transitions are animated.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFCheckBoxSetForFitSelectedMode(A3DPDFCheckBox *pCheckBox, A3DPDF3DAnnot *p3DAnnot)
This function makes the check box field be the selector for the ‘fitselected’ mode of the annot 3D. If the user checks the check box, the ‘fitselected’ mode is on ; else it is off.
This function provides a way for the final user to control the fitselected mode for an annot 3D. With it, a check box field can be associated to an annot 3D. If the user checks the box, all selections made on the 3D annot are followed by a fitselected action, i.e. the camera is zoomed to the selected node. This mode is only available when interactivity is defined using datamodel. An exemple is a scenario where you have a scroll table associated to an annot 3D, with the target behaviour kA3DPDFDataSelect. When the user selects a row in the scroll table, the corresponding node is selected in the 3D annot. Then, if the check box for ‘fitselected’ mode is checked, the camera zooms to the node. If the check box is not checked, there is no camera zoom.
- Version
13.1
- Parameters:
pCheckBox – [in] The CheckBox object to work on.
p3DAnnot – [in] The Annot 3D to work on.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code
-
A3DStatus A3DPDFCheckBoxSetForCheckAllColumn(A3DPDFCheckBox *pCheckBox, const A3DPDFScrollTable *pScrollTable, const A3DInt32 iColumnIndexInST)
This function associates the specified CheckBox with a Scroll Table column of type kA3DPDFCheckBoxContent, in order to create a ‘check/uncheck all’ CheckBox.
This function provides a way for the final user to check (or uncheck) all the CheckBoxes in a specific Scroll Table column. With it, a CheckBox field can be associated to a Scroll Table. If the user checks (respectively unchecks) the box, all the CheckBoxes of the specified Scroll Table column will also be checked (respectively unchecked).
- Version
13.2
- Parameters:
pCheckBox – [in] The CheckBox to convert into a ‘check/uncheck all’ CheckBox.
pScrollTable – [in] The Scroll Table to work on, containing a column of type kA3DPDFCheckBoxContent.
iColumnIndexInST – [in] The index of the kA3DPDFCheckBoxContent column in the Scroll Table.
- Return values:
A3D_SUCCESS –
- Returns:
A3D_SUCCESS in case of success or an error code