Command overview

Areas

Plugin Main Commands

Managing Offscreen Areas

Managing Areas

Callback and Events

Properties

Tools

Reports

Managing Reports

Properties

Input/Output

Pages

Overview

A report can have multiple pages. Each page can printed as it is or each page can printed as a report. So every page can be an independent report with its own iterations and sections. So it is possible to have a static page as a first page, followed by a report.

Page numeration

Each page have a continuous number from the first page to the last page. Also, hmReports give each page an ID which is unique. This is helpful, because you can always refer to a page after the user deletes/adds pages. If the user deletes/inserts pages, the page number of a page may differ. The ID of a page does never change.

Creating pages

Copy and paste entire pages

Getting/setting information about pages

Getting/setting the current page of the current report

Enumerating pages

Conversion between page number and reference

Deleting pages

Layers

Creating layers

List all layers

Getting/setting information about layers

Getting/setting the current layer of the current report

Sort layers

Deleting layers

Guides

Printing

Sections

Getting information about sections

Set section properties

Find a section by a coordinate

Order sections

Objects

Creating Objects

Paths

Deleting Objects

Object Properties

Scripting

Overview

A hmReports Area has it’s own variable stack. It’s a sandbox concept where you can put any variable you want into the Area . It does not intersects the variable name space of 4D. More information can be found in the chapter [[Script Execution]].

hmX

Plugin functions which starting with the prefix “hmX” are going directly on the executer/interpreter. They are indepently from the hmReports area.

Managing variable stack

Managing Methods

Getting information about script variables

Managing Scripts

Tokenize/detokenize scripts

Styled text

Overview

hmReports does support styled text for text objects. You can edit rich text in the object properties, if you enable the Multi Style property:

MultiStyle

Runs

Runs are definitions from which position to which position of the text runs a style. If text positions have no run, the default text style is used (defined by hmRep_SET OBJECT PROPERTY).

Runs should not overlap other runs; this may have unwanted results.

You can create runs with the command hmRep_CREATE STYLED TEXT RUN. With the commands hmRep_Count Runs and hmRep_GET STYLED TEXT RUN you can loop through existing commands of an object.

With hmRep_DELETE ALL RUNS you can delete all existing runs of an object.

4D Styled Text Tags

4D internally uses styled tags to save styled text into text fields and variables. A styled text looks in 4D like:

<SPAN STYLE="font-family:'Arial';font-size:10pt;text-align:left;font-weight:normal;font-style:normal;text-decoration:none;color:#000000">This is

Every SPAN STYLE is a run in hmReports. You can use the command hmRep_SET STYLED TEXT to set this 4D styled text into hmReports. hmReports automatically convert the string into runs and extract the raw text.

Multistyle in Variables, Fields and Arrays

If you use a text field, text variable or text array as a reference, you can turn on the Multi Style flag, if you want hmReports interpret the content as rich text:

MultiStyle Fields

Commands

Custom Properties

Overview

Custom properties are a powerful tool for adding custom data to an object, layer, report or area. You may need custom properties for adding your own reference-scheme. Use the command hmRep_Get Property Object to get the language-object of a report object, page, layer, report or area. With this object you can store any data (blobs, entities, entitySelections, collections…). However, keep in mind, that the object-property is saved with the report, except the properties of the hmReports-area! Database objects (entities, entitySelections) in the property will not be saved in the report!

Creating custom properties

Getting information custom properties

Search for custom properties

Enumerating custom properties

Deleting custom properties

Virtual Structure

Overview

Virtual Structure is a powerful feature of hmReports to change database and variable names into a better readable name for the user. A Virtual Structure can be defined for the entire area (default) with all it’s reports or can be defined globally. The Virtual Structure is not saved in the Report XML Definition.

The Virtual Structure is important, if you want the change table, field and variable names for the user in the object property window.

To create a Virtual Structure Item, you can use one of the hmRep_Create VStructure… commands to create a custom name. If the caption of a Virtual Structure Item, with the type of a 4D Table or 4D Field, is empty, the Table/Field is not selectable/visible in the Object Properties.

Since hmReports 2.3 it is possible to group elements like this:

VirtualStructureGroup

For more information, see chapter hmRep_Create VStructure Group.

Virtual Structure scope

Since hmReports 4.0 it is possible to define a global virtual structure. Just pass in all virtual structure commands a value of 0 as area parameter (e. g. hmRep_Create VStructure Table(0;…)). By default, each hmReports area uses it’s own virtual structure. So there will no intersections of virtual structures between hmReports areas. But if you want to create and use a global structure for all areas, you have to activate this with the area property hmRep_prop_UseVStructure.

Creating Virtual Structure Items

Enumerating Virtual Structure Items

Deleting Virtual Structure Items

Getting/setting properties of Virtual Structure Items

Searching Virtual Structure Items

Save/restore Virtual Structure

Overview

hmReports offers the developer to customize all menus with the command set. You are able to create, edit and delete items in the menu bar or in the contextual menu. Internally all menu components, including the menu bar, are menu items. Each item has an unique reference. The reference is a blackbox and is created by hmReports. With a new area the menu items references starts with 1. A reference of -1 is the contextual menu. It is no menu item itself. You can only refer to it.

Shortcuts

If the menubar is invisible in the hmReports area, all shortcuts still work. If you do not want, that shortcuts are still active, you have to catch the key events with the Callback event hmRep_OnKey.

The menubar in hmReports

menu bar

The menubar contains several standard items. To get a list of all menu bar items you have to call hmRep_GET MENU ITEM LIST:

ARRAY LONGINT($tl_items;0)
hmRep_GET MENU ITEM LIST(hmRep;0;$tl_items)

In this case you will get an array with 6 elements: {1,2,3,4,5,6} Now you can delete an item out of the menubar with:

hmRep_DELETE MENU ITEM(hmRep;6)

To get all menu items under the File menu, you have to call hmRep_GET MENU ITEM LIST with the item ID:

ARRAY LONGINT($tl_items;0)
hmRep_GET MENU ITEM LIST(hmRep;1;$tl_items)

In this case you will get an array with 12 elements: (7,8,9,10,11,12,13,14,15,16,17,18) because you have 12 menu items under this menu item: File Menu

For explanation: 7 = New report (Position 1) 8 = Open… (Position 2) 9 = Save (Position 3) 10 = Save as (Position 4) 11 = Save as SVG (Position 5) 12 = Close (Position 6) 13 = Separator (Position 7) 14 = General settings (Position 8) 15 = Report settings (Position 9) 16 = Separator (Position 10) 17 = Page settings… (Position 11) 18 = Print… (Position 12)

Important: You should handle the ID’s as a blackbox. The order and the count of the menus items may differ in future versions. You should always use hmRep_GET MENU ITEM BY ACTION to change a standard menu or you should create a completely new menu.

The menu item in hmReports

Standard menu items contains several information about an item: Item text, enable or disable, action, shortcut, reference, superior reference. You can customize all information except the references. To customize a menu item you have to use the command hmRep_SET MENU ITEM.

If you set an action to a command, some properties are set automatically. For example, if you create a menu item with the standard action #5 (delete), the item will be only active, if more than one object is selected. If you disable the item with hmRep_SET MENU ITEM, the menu item will be always disabled. Or if you set the action #57 (layer menu), the menu item will always have a submenu with all layers.

Own actions

Do identify own menu items, you can use actions between 15000 and 32000. All other actions are reserved for hmReports!

Creating menu items

Deleting menu items

Getting menu item lists

Getting and setting information about menu items

Executing menu actions

Undo

hmReports supports unlimited Undo and Redo. By default hmReports only saves the last 10 user actions to the stack. If the stack is full, the first record will be deleted, so there is space for the last action. You can change the maximum number of Undos with hmRep_SET AREA PROPERTY and the selector hmRep_prop_MaxUndos. If you pass 0 as maximum, hmReports will record unlimited undos.

Undo workflow

If a new report is opened, hmReports automatically starts an undo session. But if you want to clear the undo stack, you can start a new session by calling the command hmRep_START UNDO.

Undo actions

You can activate and deactivate several undo actions with the command hmRep_SET UNDO TYPE STATE. Some actions are deactivated by default because of performance reasons. By default, only interface actions are activated.

The following undo actions are available:

hmRep_Undo_Move (1)

Default: For interface: activated, for programming: deactivated Moving one or more objects

hmRep_Undo_Resize (2)

Default: For interface: activated, for programming: deactivated Resizing one or more objects

hmRep_Undo_Delete (3)

Default: For interface: activated, for programming: deactivated Delete one or more objects

hmRep_Undo_New (4)

Default: For interface: activated, for programming: deactivated Create one or more objects

hmRep_Undo_Change_Picture (5)

Default: For interface: deactivated, for programming: deactivated Change the picture of a picture object with the command hmRep_SET PICTURE

hmRep_Undo_Edit (6)

Default: For interface: activated, for programming: activated Can be created with hmRep_START UNDO RECORDING and hmRep_Validate Undo Recording

Commands

Ruler Units

Ruler units are measure definitions of a ruler of a report. Internally all sizes are stored in pixels. Custom units are good for displaying better readable measurements for the user. E. g. , it is better for some users to display all sizes in inch as in pixels. A ruler unit is only an overlay for the user. If you define a ruler unit, all sizes will be still stored in pixel units internally.

hmReports ruler units are defined in the area. That means, that all units and custom units (created with hmRep_Create Rulerunit) are available for all open reports in the hmReports area. hmReports initalize three standard ruler units: pixel, inch and millimeter.

A ruler unit does not have an id, it’s an index of a table starting from 1 to hmRep_Count Rulerunits. Think about it, if you create and delete units! The last ruler unit cannot be deleted.

A ruler unit record is defined as follows:

Standard definitions

If a hmReports area is opened, three ruler units are created automatically with the following properties:

Example of a ruler unit definition

The following example shows, how you can create a new custom ruler unit (my Inch).

*Pixel mapping is 72: 72 pixels are 1 inch *Short steps is 0.2: draw a small separator each 0.2 inch *Long steps is 1: draw a big separator each full inch

var $vl_ruler : Integer

$vl_ruler:=hmRep_Create Rulerunit(reparea; "my Inch"; 72; 0.2; 1)

Result:

ruler unit sample

Creating ruler units

Deleting ruler units

Getting ruler unit information

Setting ruler unit information

Enumeration of ruler units

Executer

hmReports has an integrated executer. This executer can be used independently from a reports Area. It’s a sandbox concept where you can put any variable you want into an execution context. It does not intersects the variable name space of 4D. More information can be found in the chapter Script Execution.

Managing execution contexts

Managing variable stack

Tokenize/detokenize methods

Executing scripts

Execute Code in Text

Managing methods in context

Managing virtual structure

Scripts syntax coloring

Error handling

Utilities

4D commands

PDF Tools

Utilities

Appendix