UI Function Reference¶

This is the complete catalogue of ui.* functions your program can call to drive the VDC client — set titles, hide fields, fill drop-downs, show progress, generate and print documents, raise notifications, embed a browser, and more.

Chapter 7 introduced the everyday ones with worked examples; this page is the lookup table for all of them.

How these calls work¶

Every function here runs on the VDC client (the user's desktop), not on the server where your program runs. There are two calling styles:

Object methods — you fetch an object, then call methods on it. Used for the form and its widgets:

DEFINE w ui.Window
DEFINE f ui.Form
LET w = ui.Window.getCurrent()
LET f = w.getForm()
CALL f.setFieldHidden("discount", 1)

Front-calls — you call the function directly by category and name, optionally capturing return values with RETURNING:

CALL ui.vdc.toast("Saved", "0", "3000")

DEFINE l_status INTEGER
DEFINE l_path   STRING
CALL ui.vdc.filebrowser("open", "*.csv") RETURNING l_status, l_path

Note on availability. The newer widgets (toast, dashboard, embedded browser, standalone progress dialog, charts) require a recent VDC client build. Functions that drive optional components (for example the Gantt chart) are only present when that component is compiled into the client. When in doubt, test the call in your target environment.

The form and its widgets (object methods)¶

`ui.Interface`¶

Call	Purpose
`ui.Interface.setText(text)`	Set the title shown for the current program
`ui.Interface.loadStyles(name)`	Load a named visual style (e.g. `"default"`)

CALL ui.Interface.setText("Product Entry")
CALL ui.Interface.loadStyles("default")

`ui.Window`¶

Call	Returns	Purpose
`ui.Window.getCurrent()`	`ui.Window`	The currently active window
`win.getForm()`	`ui.Form`	The form contained in that window

DEFINE w ui.Window
LET w = ui.Window.getCurrent()
IF w IS NULL THEN RETURN END IF

`ui.Form`¶

Get the form object from the current window (above), then:

Call	Purpose
`f.setFieldHidden(field, hidden)`	Hide (`1`) or show (`0`) a field
`f.setElementHidden(element, hidden)`	Hide (`1`) or show (`0`) a non-field element (group, label)

DEFINE f ui.Form
LET f = ui.Window.getCurrent().getForm()
CALL f.setFieldHidden("discount", 1)        -- hide
CALL f.setFieldHidden("discount", 0)        -- show

The form also offers two front-call helpers for dynamic styling and tab titles:

Call	Purpose
`ui.form.setattributes(field, attribute, value)`	Set a display attribute on a field (e.g. colour)
`ui.form.setpagetitle(old_title, new_title)`	Rename a notebook (tab) page

-- highlight a field in red
CALL ui.form.setattributes("amount", "backgroundColor", "#ff0000")
-- count items in a tab title
CALL ui.form.setpagetitle("Lines", "Lines (12)")

`ui.ComboBox`¶

Fetch a combo by its field name, then add and inspect items. Each item has a value (what your variable receives) and a label (what the user sees).

Call	Returns	Purpose
`ui.ComboBox.forName(field)`	`ui.ComboBox`	The combo object for a field
`cb.clear()`		Remove all items
`cb.addItem(value, label)`		Append an item
`cb.getItemCount()`	INTEGER	Number of items
`cb.getItemText(index)`	text	The label of item `index` (0-based)
`cb.getItemName(index)`	text	The value of item `index` (0-based)

DEFINE cb ui.ComboBox
LET cb = ui.ComboBox.forName("category")
CALL cb.clear()
CALL cb.addItem("F", "Food")
CALL cb.addItem("D", "Drink")

VDC client services (`ui.vdc.*`)¶

These front-calls reach into the desktop: files, documents, printing, notifications, hardware and more. Most return a status code (1 or "0" on success — see each group); capture it with RETURNING.

Client information¶

Call	Returns	Purpose
`ui.vdc.version()`	version string	The VDC client version (compatibility checks)
`ui.vdc.mdi()`	`1` = MDI, `0` = SDI	Whether modules share one window
`ui.vdc.getdevice(html)`	type, info	Client device type and capabilities

DEFINE l_version STRING
CALL ui.vdc.version() RETURNING l_version

Files and the clipboard¶

Call	Returns	Purpose
`ui.vdc.filebrowser(mode, filter)`	status, path	File open/save dialog. `mode`: `"open"` / `"savefile"`
`ui.vdc.execute(target)`	result	Open a file/URL/folder with its default app
`ui.vdc.setclipboard(text)`	—	Copy text to the clipboard
`ui.vdc.md5hashfile(file)`	hash	MD5 hash of a client-side file
`ui.vdc.getbasename(path)`	filename	Original name of a drag-and-dropped file
`ui.vdc.getopenwithprogram(ext)`	program	Which program handles a file extension

DEFINE l_status INTEGER
DEFINE l_path   STRING
CALL ui.vdc.filebrowser("open", "*.csv") RETURNING l_status, l_path
IF l_status = 1 AND LENGTH(l_path CLIPPED) > 0 THEN
    DISPLAY "User chose: ", l_path
END IF

CALL ui.vdc.execute("https://example.com/help")   -- open a URL
CALL ui.vdc.setclipboard("Order #12345")

Documents and printing¶

Call	Returns	Purpose
`ui.vdc.repgen(odf, sed, dest)`	result, message	Merge an ODF template with substitutions
`ui.vdc.odftopdf(src, dest)`	result, message	Convert an ODF document to PDF (LibreOffice)
`ui.vdc.checkodffile(odf, dest)`	result	Validate / repair an ODF template
`ui.vdc.printpdf(file)`	result	Print a PDF on the client's default printer
`ui.vdc.openeditor(type, file)`	result	Open a file in an editor (`"html"`/`"word"`/`"excel"`/`"text"`)
`ui.vdc.texteditor(file, wrap, digits)`	result	Open a file in the built-in text editor (`wrap`/`digits`: `1`/`0`)
`ui.vdc.getstdtableprog()`	path / `0`	The default spreadsheet program, if any
`ui.vdc.getstdocumentprog()`	path / `0`	The default word processor, if any
`ui.vdc.ignoreofficeversion(type)`	result	Bypass Office version checks for this session

DEFINE l_result INTEGER
DEFINE l_msg    CHAR(200)
CALL ui.vdc.odftopdf("/tmp/offer.odt", "/tmp/offer.pdf") RETURNING l_result, l_msg
IF l_result = 1 THEN CALL ui.vdc.printpdf("/tmp/offer.pdf") RETURNING l_result END IF

Notifications and feedback¶

Call	Purpose
`ui.vdc.toast(message, type, duration)`	In-window toast. `type`: `"0"` ok / `"1"` error / `"2"` warning / `"3"` info; `duration` in ms
`ui.vdc.systraymessage(title, message)`	OS notification-centre / system-tray message
`ui.vdc.playsound(sound)`	Play a named sound (`"beep"`, `"error"`) or a file
`ui.vdc.dial(number)`	Dial a phone number (CTI/TAPI integration)

CALL ui.vdc.toast("Record saved", "0", "3000")          -- green, 3 s
CALL ui.vdc.systraymessage("Report ready", "Sales report generated")

Charts and help¶

Call	Returns	Purpose
`ui.vdc.openchartwindow(type, csvfile)`	result	Show a chart from CSV (`"bar"`/`"line"`/`"pie"`/`"area"`)
`ui.vdc.fieldhelp(title, htmlText)`	result	Show field help in a styled popup (HTML)
`ui.vdc.openhelp(lang, helpid)`	result	Open a local help page in the browser
`ui.vdc.openhelpeditor(lang, helpid, title, helptype)`	result	Open the Markdown help editor

Data, state and integration¶

Call	Returns	Purpose
`ui.vdc.get_last_sort(module)`	sort text	The user's last saved sort order for a module
`ui.vdc.settingsonserver()`	result	Sync client settings with the server
`ui.vdc.backgroundresponse(type, status, data)`	—	Send background data (dashboard/KPI/etc.) as JSON
`ui.vdc.history_add(company, user, module, table, key, code, label)`	—	Add an entry to the client's navigation history
`ui.vdc.action(p1, … p10)`	result, message	Generic extension call (custom integrations)

Status-bar progress (`ui.vdc.progress_*`)¶

A lightweight progress indicator in the form's status bar — no separate window.

Call	Purpose
`ui.vdc.progress_start(text)`	Show the indicator with a message
`ui.vdc.progress_update(percent, text)`	Update it (`percent` `0`–`100`, or `<0` for "busy")
`ui.vdc.progress_stop()`	Hide it

CALL ui.vdc.progress_start("Importing...")
FOR i = 1 TO n
    CALL ui.vdc.progress_update((i * 100) / n, "Row " || i)
    -- ... process row i ...
END FOR
CALL ui.vdc.progress_stop()

Embedded browser (`ui.browser.*`)¶

Control an embedded web view inside the client.

Call	Returns	Purpose
`ui.browser.create()`	id	Create a browser instance
`ui.browser.openurl(id, url)`	—	Navigate to a URL
`ui.browser.close(id)`	—	Close the browser

DEFINE l_browser INTEGER
CALL ui.browser.create() RETURNING l_browser
CALL ui.browser.openurl(l_browser, "https://example.com")

Standalone progress dialog (`ui.progress.*`)¶

A modal progress dialog window (heavier than the status-bar version above).

Call	Returns	Purpose
`ui.progress.create()`	id	Create the dialog
`ui.progress.show(id)`	—	Show it
`ui.progress.hide(id)`	—	Hide it (keep it alive)
`ui.progress.settitle(id, title)`	—	Set the window title
`ui.progress.settext(id, text, percent)`	—	Update text and percentage
`ui.progress.close(id)`	—	Close and destroy it

DEFINE l_pd INTEGER
CALL ui.progress.create() RETURNING l_pd
CALL ui.progress.settitle(l_pd, "Printing invoices")
CALL ui.progress.show(l_pd)
FOR i = 1 TO n
    CALL ui.progress.settext(l_pd, "Invoice " || i || " of " || n, (i * 100) / n)
END FOR
CALL ui.progress.close(l_pd)

Inline form progress (`ui.form.progress.*`)¶

A progress indicator embedded in the current form (no dialog, no status bar).

Call	Purpose
`ui.form.progress.start(text)`	Show the inline indicator
`ui.form.progress.update(percent, text)`	Update it (`percent` `0`–`100`, or `<0` for "busy")
`ui.form.progress.stop()`	Hide it

Menu options (`ui.menu.*`)¶

Call	Purpose
`ui.menu.showhide(option1, vis1, option2, vis2, …)`	Show/hide several menu options at once. `vis`: `"Y"` show / `"N"` hide

-- show "print", hide "delete" in one call
CALL ui.menu.showhide("print", "Y", "delete", "N")

Dashboard widgets (`ui.dashboard.*`)¶

Manage the client's dashboard tiles (KPIs, gauges, planners).

Call	Purpose
`ui.dashboard.additem(name, icon, text, value, [tooltip, trend, subscribed, history, type])`	Add or update a widget
`ui.dashboard.removeitem(name, company, db)`	Remove a widget
`ui.dashboard.getabonnements(company, db)`	Fetch the user's subscribed widgets (async)

The additem parameters, in order:

#	Parameter	Description
0	`name`	Unique widget identifier
1	`icon`	Icon file name
2	`text`	Widget title
3	`value`	Value / content text
4	`tooltip`	Tooltip (optional)
5	`trend`	Trend indicator, e.g. `"+5%"` (optional)
6	`subscribed`	`"1"` subscribed, `"0"` not (optional)
7	`history`	JSON array for a sparkline (optional)
8	`type`	`"kpi"`, `"gauge"`, `"planer"` (optional)

Gantt chart (`ui.gantt.*`)¶

A Gantt chart widget. Only available when the client is built with the chart component.

Call	Returns	Purpose
`ui.gantt.create()`	id	Create a Gantt chart
`ui.gantt.readcsv(id, csvfile)`	—	Load chart data from CSV
`ui.gantt.setTitle(id, title)`	—	Set the chart title

A combined example¶

Let the user pick a CSV file, import it with a progress bar, and confirm with a toast:

FUNCTION import_csv()
    DEFINE l_status INTEGER
    DEFINE l_path   STRING
    DEFINE i, n     INTEGER

    CALL ui.vdc.filebrowser("open", "*.csv") RETURNING l_status, l_path
    IF l_status != 1 OR LENGTH(l_path CLIPPED) = 0 THEN
        RETURN
    END IF

    LET n = count_rows(l_path)            -- your own function
    CALL ui.vdc.progress_start("Importing...")
    FOR i = 1 TO n
        CALL ui.vdc.progress_update((i * 100) / n, "Row " || i || " of " || n)
        CALL import_row(i)                -- your own function
    END FOR
    CALL ui.vdc.progress_stop()

    CALL ui.vdc.toast("Imported " || n || " rows", "0", "3000")
END FUNCTION

That completes the developer guide. Return to the overview, or jump back to Talking to the VDC Client for the guided introduction to these calls.

UI Function Reference¶

How these calls work¶

The form and its widgets (object methods)¶

ui.Interface¶

ui.Window¶

ui.Form¶

ui.ComboBox¶

VDC client services (ui.vdc.*)¶