User Defined UI Block (UDB)

A User Defined UI Block (UDB) is a custom block, similar to a dialog, containing a set of blocks where the behavior is governed by its own automation code. After you create a UDB (a .dlx file), you can use it on a dialog like a standard block. The dialog's application code interacts with the UDB's application code to make the behavior complete; together, the dialog and UDB .dlx files make the application complete. A complete application enables a successful dialog launch with the UDB as one of the constituent blocks of the dialog.

This page consolidates the whole "User Defined UI Block" chapter of the Block UI Styler book: the UDB concept, creating a UDB, positioning items inside it, using it inside a dialog, how dialog execution/library-building works, per-callback cascading order across nested UDBs, and catalog (palette) management.

Multi Instance and Multi Level

• Multi Instance: You can use any number of UDB instances on the dialog. The dialog automation code has an equal number of UDB instances. The dialog automation code needs to be built with the UDB's automation code/DLL.
• Multi level: A UDB can contain another UDB as one of its constituent blocks. Such containment is allowed to any level — for example, a two-level UDB can have a UDB that contains another UDB.

Note: You can modify an existing function only if the parameter list is unchanged. You can manage the .dlx file of a UDB independently without affecting the dialog application.

Where do I find it?

Application	Block UI Styler
Location in dialog box	Dialog dialog box → Type group → User Defined UI Block

---

Create a UDB

UDB creation is similar to dialog creation: blocks are added to the UDB and desired properties are set on the block.

1. Choose File tab → All Applications → Block UI Styler.
2. In the Type group, select User Defined UI Block.

Catalog Specific code generation options

These options are required for generation of the catalog file and representation on the block palette.

Option	Description
Block Name	UDB name that appears on the catalog. By default, the .dlx file name is set as the block's name.
Block Icon	When the UDB is used in a dialog, this icon is displayed against the UDB entry on the dialog property window. You can provide icons of any size such as 24×24, 32×32. The recommended icon size is 16×16 high-quality bitmaps.
Catalog Tooltip	Tooltip text shown when you hover the mouse over the UDB's name in the catalog.
Catalog Category	Category under which the UDB (referred to in-source as "CD-Block") is shown in catalog.

Files produced when saving a UDB

• Catalog file (.udx): This file is similar to the dialog file, containing information about blocks and their properties. It manages the catalog entry on the palette — you can change the UDB category, name, and other attributes in this file. NX searches for this file using the same rule applicable for .dlx file search (e.g., searching in user directories).
• Automation code (VB.NET, C#, C++, Java, or Python): This file captures the behavior of the UDB. You must provide the implementation in this file.

A UDB may contain another UDB, allowing multi-level UDB.

---

Position dialog items in a UDB

You can position dialog items in a UDB using the Attachments property. You can position these items with respect to other dialog items or the UDB border. Dialog items consist of blocks in the Block Catalog folder, such as Toggle, Integer, String, and so on.

Note: The Block UI Styler requires an open part in NX.

Steps:

1. In the Dialog dialog box, from the Type list, select User Defined UI Block.
2. In the Block Catalog, expand any folder and click the blocks to add them to the Dialog dialog box.
3. In the Dialog dialog box, the blocks are displayed in the Blocks group on the User Defined UI Block tab. The dialog items are also displayed in the untitled UDB in the sequence you add them. You can modify a dialog item's visibility using the Show property, including at runtime.
4. On the User Defined UI Block tab, in the Blocks group, select the dialog items you want to position.
5. In the Properties group, expand the Other list.
6. In the Attachments list, right-click your preferred position from Bottom, Left, Right, Top, and select the required dialog item.

Note: If you attach a visible dialog item to an invisible dialog item, the visible dialog item is displayed at the top of the UDB instead of below the invisible dialog item. Also, if you modify a dialog item's visibility to off (not visible) at runtime, any attached dialog items will shift up or left to the next visible dialog item or to the UDB's edge.

In case of improper attachments, such as circular attachments, the UDB may behave unexpectedly. In such cases, change the position of the attachments as required.

(Optional) To position a dialog item with reference to the UDB edge, right-click your preferred position and select Dialog. Select Default to revert to the dialog item's default position.

---

Using UDB in dialog design

The UDB must be available on the block palette so you can select it and place it on the dialog. NX searches for the UDB's .dlx file using the rule applicable for searching the dialog's own .dlx file. If found, the UDB is added to the dialog; otherwise a message about the missing .dlx file is displayed. You must ensure the UDB .dlx files are placed in the appropriate application-subdirectory of the user directory, e.g. %UGII_USER_DIR%\application.

Once added, the UDB supports simple operations such as cut, paste, move, etc., similar to standard blocks. The UDB has general properties as the property of the block.

Note: The UDB displayed at design time is only for representation — it will not display behavioral aspects implemented in automation code.

Files created on saving the dialog

• .dlx file: Dialog file containing the information of the standard block and the UDB. This dialog is incomplete if the UDB's .dlx file is unavailable.
• Automation code (VB.NET, C#, C++, Java, or Python): This file captures the behavior of the UDB — you must provide the implementation.

Dialog callback relevance to UDB

Focus Notify callback may be required if the dialog contains a UDB. You must generate this callback during dialog design. During dialog execution, this callback is invoked if the UDB receives or loses focus.

---

Dialog execution

Dialog execution requires the following files:

• Dialog's library: Executed to launch the dialog.
• Dialog's .dlx file: Represents constituent blocks of the dialog.
• UDB's library: Optional — required only when the dialog library is built with the UDB's library (i.e., linked externally). If the dialog library is built with the UDB source code directly, the UDB's library is not required.
• UDB's .dlx file: Represents constituent blocks of the UDB. If unavailable, the dialog launch fails. For multi-level UDB, the .dlx of each level must be available.

Create dialog application library

There are two ways to create the dialog application library:

1. UDB source code: Build the dialog and the UDB source code together to create the dialog application library.
2. UDB library: Build the dialog's source code with the UDB's library to create the dialog application library. For dialog execution, the UDB library must be available in this case.

Catalog management

The catalog file is an XML file with a .udx extension. NX searches for it in the user directories, and it is subsequently populated onto the Block Catalog. Any number of .udx files can be present in the system. A single .udx file may contain more than one UDB, under the same or different categories, and you can specify the same category across different .udx files. It is recommended to manage the block catalog through the .udx files.

To refresh the catalog with a new .udx file, right-click and select Refresh on the palette. When a new UDB is saved, the palette refreshes automatically, displaying the catalog entry for the new UDB.

---

Callback cascading

Callbacks of the UDB and the dialog participate at various stages of a dialog's existence. For example, if you modify a block available on the UDB, the update callback defined in the UDB's automation code executes first, followed by the update callback of the dialog. The first update callback receives the block as an argument; the second callback receives the UDB.

Worked example: two-level UDB

Consider a two-level UDB system where the dialog contains a UDB that contains another UDB:

• Level-1 UDB = L1
• Level-2 UDB = L2
• Dialog = D

D contains L2, and L2 contains L1.

Callback	Order invoked	Additional information
Initialize	UDB's followed by Dialog's: L1 → L2 → D	—
Dialog shown	UDB's followed by Dialog's: L1 → L2 → D	—
Update (value entered in core block of L1)	UDB's followed by Dialog's: L1 → L2 → D	L1 receives the core block as argument, L2 receives L1 as argument, D receives L2 as argument.
Focus (from selection block of D to selection block of L1)	Lose Focus: Only Dialog's (D). Gain Focus: UDB's — L1.	—
Keyboard Focus (from core block of dialog to core block of L1)	Lose Focus: Only Dialog's (D). Gain Focus: UDB's followed by Dialog's: L1 → L2 → D	L1 receives core block as argument, L2 receives L1 as argument, D receives L2 as argument.
OK / Apply / Cancel	Only Dialog's (D)	—
Enable OK/Apply Button	Dialog's followed by UDB's: D → L2 → L1	—

Key takeaways from the cascading table:

• Most callbacks fire innermost-first (L1 → L2 → D) — the deepest-nested UDB's automation code runs before its parent UDB's, which runs before the top-level dialog's.
• OK/Apply/Cancel are the exception: they exist only at the Dialog level (D), never at UDB levels.
• Enable OK/Apply Button is the other exception: it is evaluated outermost-first (D → L2 → L1) — the reverse order from most other callbacks, since the dialog needs to poll each nested UDB with the button-state question.
• Focus and Keyboard Focus distinguish "Lose Focus" (only ever fired at the Dialog level) from "Gain Focus" (cascades through the UDB chain), reflecting that focus loss is a single dialog-wide event while focus gain must bubble to whichever nested block actually received it.