DBM Events

At this time, DBM supports only three events.

The following chapters in this page describe when an event is fired. To connect the firing of an event to a script, you must define a specific script called “InitMacroEvents” which is also described in this page.

What is a “grid”?

The term “grid” is used frequently in this page. It refers to a rectangular section of the DBM user interface which contains a list of items, grouped into line (rows) and columns.

DBM has the following grids; names are spelled out in the way used in scripts.

The “TABLES” grids (in the top left position) lists database tables along with some of their properties. You click a line in this grid to open a table.
The “ENTRIES” grid (main portion of he screen) lists entries in the selected table. “MAIN” is an alias for “ENTRIES”.
The lower right area can hold one of the following grids:
- “SEARCH_RESULTS” displays the result of a multi-table search
- “GROUP_MEMBERS” shows which elements are contained in the selected group, story, etc.
- “COLLECTION_MEMBERS” shows the members of the selected collection. This is similar to “GROUP_MEMBERS” but technically different, hence the distinct name.

Grid Drawing Events

Grid drawing events are fired in the context of a specific grid. They provide a common set of global variables to the script, and expect a result in the form of a JSON value.

Please refer to the documentation page DBM Scripting for details in variables, on how to create JSON values, and on how to return the result of script execution.

These global variables are defined in all grid events:

Name	Content
`$Grid`	Name of the grid for which the event is fired.
`$TotalRows`	Number of rows in this grid (this is not necessarily the same as number of entries in a table).
`$TotalColumns`	Number of columns in this grid (including columns scrolled out of view).
`$RowIndex`	Row index; `-1` if the event is not for a specific row. The top-most row has index `0`, and the bottom-most row has index `$TotalRows-1`.
`$ColumnIndex`	Column index; `-1` if the event is not for a specific column. The left-most column has index `0`, and the right-most column has index `$TotalColumns-1`.
`$ColumnWidth`	Width in pixels of the column; `-1` if the event is not for a specific column.
`$ColumnTitle`	Title of the column; an empty string if the event is not for a specific column. Column titles are localized into the selected GUI language; some column titles can even be configured.
`$FieldName`	Internal (technical) name of the field which is displayed in this column; an empty string if the event is not for a specific column. Field names are not localized and cannot be configured.
`$FieldValue`	Value (data) in the grid cell; an empty string if the event is not for a specific cell

PreDrawGrid Event

Every time DBM starts drawing a grid, it fires the PreDrawGrid event. Currently, this event can be used to disable inplace editing of specific grid columns. For example, it can make certain custom fields read-only.

PreDrawGrid is fired when DBM starts up and creates its user interface, but it is also fired when the grid needs redrawing because its content has changed (or may have changed).

If the handler wants to modify the grid’s default behaviour, it should return a JSON object with the following layout:

JSON

{
  "inplace-edit":
  {
    "column1": "enabled",
    "column2": "disabled",
    ...
  }
}

The “column1” etc. names should be column titles or field names; and “enabled” or “disabled” enables or disables inplace editing of this field in the grid.

Inplace editing is enables by default for all fields where it is technically possible; the “enabled” value is only provided for completeness.

Invalid entries are ignored.

PreDrawGridLine Event

The PreDrawGridLine event is fired when DBM begins to draw a line in a grid, once for each line. The connected script can define that this line should have a non-default background color.

To define the background color for this line, the hander should return a JSON object like this:

JSON

{
  "background-color": color-spec
}

The “color-spec” part can have of of these forms:

color-spec	Explanation
a color name (e.g. “red”)	One of the extended color names defined by CSS3 (see https://en.wikipedia.org/wiki/Web_colors#Extended_colors)
RGB(r,g,b)	RGB value with components r, g, and b
JSON `{ "scheme-color": "name", "default": "default-color" }`	Takes the color from the named parameter of the selected UI color scheme. The “default” part is optional and follows one of the forms mentioned above.
JSON `{ "config-value": "key\\name", "default": "default-color" }`	Reads the color from a configuration value. If “key” doesn’t start with a backslash, it is a subkey of “DBM”. The “default” part is optional and follows one of the forms mentioned above.

By defining the color as a part of the UI color scheme, you can create satisfactory contrasts even if users prefer different schemes, because the actual value is always taken from the user’s selected scheme.

PreDrawGridField Event

This event is fired before DBM draws a grid field (also called a “cell”). The connected macro can modify the displayed content in various ways.

To modify the text which is displayed in the grid cell, the handler should return this JSON object:

JSON

{
  "mode": "text",
  "text": "Text to display"
}

To display icons instead of text, the returned object should look like this:

JSON

{
  "mode": "icons",
  "icons":
  [
    {
      "path": "C:\\path\to\\file.bmp"
    },
    {
    },
    {
      "path": "C:\\path\to\\iconfile.png",
      "number_of_icons": 5,
      "index": 3
    }
  ]
}

This displays the icon from the file.bmp file in the first (left-most) position, then nothing (the background color shines through) in the second position, and from the iconfile.png the icon at index 3 out of 5.

The last form enables you to place more than one icon into a file, in a horizontal row, and select the one to display by its (0-based) index.

Connecting Events to Scripts

DBM fires events every time the respective situation arises. An event, however, only has an effect when you connect it to a script which is then executed. The connection from events to scripts is established when DBM starts up, via a macro that is stored in the “InitMacroEvents” parameter.

Example:

CODE

AddEvent("PreDrawGrid", "PreDrawGrid_Handler", "ENTRIES, GROUP_MEMBERS, SEARCH_RESULT")
AddEvent("PreDrawGridLine", "PreDrawGridLine_Handler", "ENTRIES, SEARCH_RESULT")
AddEvent("PreDrawGridField", "PreDrawGridField_Handler", "ENTRIES, GROUP_MEMBERS, SEARCH_RESULT", "CUSTOM/EXTRA_FIELD")

This script, stored in “InitMacroEvents”, connects each of the events described in this page with its respective handling script. This connection is only made for specific grids, and in the case of the “PreDrawGridField” event, only for a specific column. In this example, this is a custom defined column, but it could be any standard column as well.