> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/api-and-command-reference/scra-dynafamily-programmers-manual/commands/user-interface-command-group-0x18nn/display-flexible-ui-pages-display-only-command-0x1830/ui-page-option-0x03-layout.md).

# UI Page Option 0x03 Layout

The host uses this option to display a page with the following elements: a title, a section for uploading a custom image, an option at the bottom-left corner to display either the Device Serial Number or host-provided text, and a maximum of one functional green button positioned on the right.

The title and functional button are labeled with String IDs associated with configured String messages. See Table – Default User Interface String IDs and Strings. 

When the user presses this button, the device sends a notification to the host to indicate the corresponding button is pressed. See User Interface Host Action Request - Notification 0x1803. After that, the host will decide what to do next.

Recommend maximum number of characters and bitmap image setting for this page:

{% stepper %}
{% step %}

### Landscape Screen Orientation

* Title text can fit about:
  * 18 Upper case wide size characters like “WM”
  * 23 Upper case regular size characters like “ABC”
  * 21 lower case wide size characters like “wm”
  * 30 lower case regular size characters like “abc”
* Bottom left corner text can fit about:
  * 8 Upper case wide size characters like “WM”
  * 12 Upper case regular size characters like “ABC”
  * 9 lower case wide size characters like “wm”
  * 15 lower case regular size characters like “abc”
* Functional button text can fit about:
  * 5 Upper case wide size characters like “WM”
  * 8 Upper case regular size characters like “ABC”
  * 6 lower case wide size characters like “wm”
  * 9 lower case regular size characters like “abc”
* Bitmap image
  * Maximum width: 320px
  * Maximum height: 140px
  * Color depth: 24-bit (True Color, RGB), 16-bit (5:5:5:1, RGB Hi Color), 8-bit (256 Color), 4-bit (16 Color), or 1-bit (monochrome)
    {% endstep %}

{% step %}

### Portrait Screen Orientation

* Title text can fit about:
  * 13 Upper case wide size characters like “WM”
  * 17 Upper case regular size characters like “ABC”
  * 14 lower case wide size characters like “wm”
  * 20 lower case regular size characters like “abc”
* Bottom left corner text can fit about:
  * 8 Upper case wide size characters like “WM”
  * 12 Upper case regular size characters like “ABC”
  * 9 lower case wide size characters like “wm”
  * 15 lower case regular size characters like “abc”
* Functional button text can fit about:
  * 4 Upper case wide size characters like “WM”
  * 6 Upper case regular size characters like “ABC”
  * 5 lower case wide size characters like “wm”
  * 7 lower case regular size characters like “abc”
* Bitmap image
  * Maximum width: 240px
  * Maximum height: 220px
  * Color depth: 24-bit (True Color, RGB), 16-bit (5:5:5:1, RGB Hi Color), 8-bit (256 Color), 4-bit (16 Color), or 1-bit (monochrome)
    {% endstep %}
    {% endstepper %}

<figure><img src="/files/lugNDpk4CvJsGF4bytLh" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/ufeXLKMv2RIyYFxiCDST" alt=""><figcaption></figcaption></figure>

## Table UIPO-1 – Request Data for Command 0x1830

<table><thead><tr><th>Tag</th><th width="77">Len</th><th width="253">Value / Description</th><th width="78.3333740234375">Typ</th><th width="74.333251953125">Req</th><th width="98.6666259765625">Default</th></tr></thead><tbody><tr><td>Beginning of any wrappers, at minimum including <strong>Response Message</strong> </td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>1830 = <strong>Display Flexible UI Pages (Display Only) - Command 0x1830</strong></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>81</td><td>01</td><td><p>Display Time</p><ul><li>0x00 – Infinitive. Device leaves the requested page on the display until the host initiates a change.</li><li>0x01 to 0xFF = RFU</li></ul></td><td>B</td><td>R</td><td></td></tr><tr><td>82</td><td>01</td><td><p>UI page option</p><ul><li>0x00 – Page with up to 5 lines of text and up to 1 functional button Middle. See Tag A1.</li><li>0x01 – Page with a title, up to 6 buttons with text, and up to 3 functional buttons. See Tag 83, A2 and A4.</li><li>0x02 – Page with a title, up to 6 buttons with $Amount, and up to 3 functional buttons. See Tag 83, A3 and A4.</li><li>0x03 – Page with a title, a custom image, an optional bottom left corner with SN or Text, and up to 1 functional button Right. See Tag 83 and A5.</li><li>0x06 – Flexible UI Gen. 2 page. Displays an image and sends touch notifications. See tag 83, A8.</li></ul></td><td>B</td><td>R</td><td></td></tr><tr><td>83</td><td>02</td><td>Text String ID for a tile of UI page option: 0x01, 0x02, 0x03 See <strong>Table 361 – Default User Interface String IDs and Strings</strong> If host wants to disable this title, do not include this tag.</td><td>B</td><td>O</td><td></td></tr></tbody></table>

## Table UIPO-2 – Request Data for Command 0x1830 - A1–A8 and sub-tags:

<table><thead><tr><th width="74.33331298828125">Tag</th><th width="75.66668701171875">Len</th><th>Value / Description</th><th width="80.66668701171875">Typ</th><th width="74.6666259765625">Req</th><th width="96">Default</th></tr></thead><tbody><tr><td>A1</td><td>var</td><td>Text string parameters for UI page option: 0x00 The parameter in this TLV data object allow the host to enable and disable the data base for UI page option 0x00</td><td>B</td><td>O</td><td></td></tr><tr><td>/81</td><td>var</td><td>Text string (&#x3C;= 30 characters) for line 1, end with NULL char. If host wants to disable this line, do not include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/82</td><td>var</td><td>Text string (&#x3C;= 30 characters) for line 2, end with NULL char. If host wants to disable this line, do not include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/83</td><td>var</td><td>Text string (&#x3C;= 30 characters) for line 3, end with NULL char. If host wants to disable this line, do not include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/84</td><td>var</td><td>Text string (&#x3C;= 30 characters) for line 4, end with NULL char. If host wants to disable this line, do not include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/85</td><td>var</td><td>Text string (&#x3C;= 30 characters) for line 5, end with NULL char. If host wants to disable this line, do not include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/86</td><td>02</td><td>Function button Middle option. String ID = Enable functional button Middle with a String ID associated with a configured String message. See <strong>Table XXX – Default User Interface String IDs and Strings</strong> When user presses this button, device sends notification to the host to indicate the functional button Middle is pressed. See <strong>User Interface Host Action Request - Notification 0x1803</strong> If host wants to disable this button, do not include this tag</td><td>B</td><td>O</td><td></td></tr><tr><td>A2</td><td>var</td><td>Button text String ID parameters for UI page option: 0x01 and 0x02. The parameter in this TLV data object allows the host to enable and disable the data base. When user presses any button, device sends notification to the host to indicate which button is pressed. See <strong>User Interface Host Action Request - Notification 0x1803</strong></td><td>B</td><td>O</td><td></td></tr><tr><td>/81</td><td>02</td><td>Text String ID for button 1. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/82</td><td>02</td><td>Text String ID for button 2. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/83</td><td>02</td><td>Text String ID for button 3. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/84</td><td>02</td><td>Text String ID for button 4. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/85</td><td>02</td><td>Text String ID for button 5. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/86</td><td>02</td><td>Text String ID for button 6. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>A3</td><td>var</td><td>Button $Amount parameters for UI page option: 0x01, 0x02 The parameter in this TLV data object allows the host to enable and disable the data base for UI page option 0x01 and 0x02 When user presses any button, device sends notification to the host to indicate which amount button is pressed. See <strong>User Interface Host Action Request - Notification 0x1803</strong></td><td>B</td><td>O</td><td></td></tr><tr><td>/81</td><td>04</td><td>Value $Amount for button 1. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/82</td><td>04</td><td>Value $Amount for button 2. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/83</td><td>04</td><td>Value $Amount for button 3. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/84</td><td>04</td><td>Value $Amount for button 4. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/85</td><td>04</td><td>Value $Amount for button 5. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/86</td><td>04</td><td>Value $Amount for button 6. If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>A4</td><td>var</td><td>Functional buttons parameters for UI page option: 0x01 and 0x02. The parameter in this TLV data object allows the host to enable and disable the data base. When user presses any button, the device sends notification to the host to indicate which functional button is pressed. See <strong>User Interface Host Action Request - Notification 0x1803</strong></td><td>B</td><td>O</td><td></td></tr><tr><td>/81</td><td>03</td><td>Text String ID and color option for functional button Left. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. Byte 0-1: String ID Byte 2: color option 0x00 = red 0x01 = green 0x02 = yellow If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/82</td><td>03</td><td>Text String ID and color option for functional button Middle. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. Byte 0-1: String ID Byte 2: color option 0x00 = red 0x01 = green 0x02 = yellow If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/83</td><td>03</td><td>Text String ID and color option for functional button Right. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. Byte 0-1: String ID Byte 2: color option 0x00 = red 0x01 = green 0x02 = yellow If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>A5</td><td>var</td><td>Parameters for UI page option 0x03 The parameter in this TLV data object allow the host to enable and disable the data base</td><td>B</td><td>O</td><td></td></tr><tr><td>/81</td><td>02</td><td>Text String ID for green functional button Right. See <strong>Table XXX – Default User Interface String IDs and Strings</strong>. When user presses this button, device sends notification to the host to indicate the functional button Right is pressed. See <strong>User Interface Host Action Request - Notification 0x1803</strong> If host wants to disable this button, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/82</td><td>02</td><td>X Position. If host wants device to display the image in the center of the loading image area, don’t include this tag.</td><td>B</td><td>O</td><td></td></tr><tr><td>/83</td><td>02</td><td>Y Position. If host want device to display the image in the center of the loading image area, don’t include this tag Note: Y pos >= 50px Y pos + Image Height &#x3C;= 190px Landscape Screen Orientation Y pos + Image Height &#x3C;= 270px Portrait Screen Orientation</td><td>B</td><td>O</td><td></td></tr><tr><td>/84</td><td>var</td><td>Bitmap Image encoded in full BMP file format as defined by Microsoft (e.g, starting with “BM”) Image Width Max = 320px Landscape Screen Orientation Image Height Max = 140px Landscape Screen Orientation Image Width Max = 240px Portrait Screen Orientation Image Height Max = 220px Portrait Screen Orientation</td><td>B</td><td>O</td><td></td></tr><tr><td>/85</td><td>var</td><td><p>Bottom left corner option Byte 0 = option</p><ul><li>0x00 = Disable</li><li>0x01 = show Device Serial Number</li><li>0x02 = show text</li><li>0x03..0x0F = invalid</li></ul><p>Byte 1 = length of the text, should be less than 16 characters. Byte 2..N = text string value.</p></td><td>B</td><td>0</td><td></td></tr><tr><td>A8</td><td>Var</td><td>Parameters for UI page option 0x06</td><td>B</td><td>O</td><td></td></tr><tr><td>/81</td><td>2</td><td>Image X position (omit for default centered position)</td><td>B</td><td>O</td><td></td></tr><tr><td>/82</td><td>2</td><td>Image Y position (omit for default centered position)</td><td>B</td><td>O</td><td></td></tr><tr><td>/83</td><td>1</td><td>Image ID (for image stored on device). Value is 0-3 for the 4 available image ‘slots’. Must be signed image for touch notifications to be sent. Cannot be used in the same command as /84.</td><td>B</td><td>O</td><td></td></tr><tr><td>/84</td><td>var</td><td>Image data. Image encoded in full BMP file format as defined by Microsoft (e.g, starting with “BM”) <strong>OR</strong> contents of .bin file for Magtek signed image file. Must be signed .bin data for touch notifications to be sent. Cannot be used in the same command as /83.</td><td>B</td><td>O</td><td></td></tr><tr><td>End of any wrappers, at minimum <strong>Response Message</strong> </td><td></td><td></td><td></td><td></td><td></td></tr></tbody></table>

## Table UIPO-3 - Display Flexible UI Pages (Display Only) - Response Data for Command 0x1830

<table><thead><tr><th>Tag</th><th width="79.66668701171875">Len</th><th width="125.3333740234375">Value / Description</th><th width="74.3333740234375">Typ</th><th width="74.66668701171875">Req</th><th width="98">Default</th></tr></thead><tbody><tr><td>Beginning of any wrappers, at minimum including <strong>Response Message</strong> </td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>1830 = <strong>Display Flexible UI Pages (Display Only) - Command 0x1830</strong></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>No parameters</td><td></td><td></td><td></td><td></td><td></td></tr><tr><td>End of any wrappers, at minimum including <strong>Response Message</strong> </td><td></td><td></td><td></td><td></td><td></td></tr></tbody></table>

If the request started successfully, the Request Status in the message wrapper is **All good / requested operation was successful**.

## Table UIPO-4 - Request Example

{% code title="Example (Hex)" %}

```
AA 00 81 04 01 2C 18 30 84 1A 18 30 81 01 00 82 01 00 83 02 00 05 A1 0C 83 0A 54 48 41 
4E 4B 20 59 4F 55 00
```

{% endcode %}

## Table UIPO-5 - Response Example

{% code title="Example (Hex)" %}

```
AA008104822C1830820400000000
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.magtek.com/api-and-command-reference/scra-dynafamily-programmers-manual/commands/user-interface-command-group-0x18nn/display-flexible-ui-pages-display-only-command-0x1830/ui-page-option-0x03-layout.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.