taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

cash-keypad-submit-is-cut-off.md (5550B)


      1 <!--
      2   This file is part of GNU Taler
      3   (C) 2026 Taler Systems S.A.
      4 
      5   GNU Taler is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     12 
     13   You should have received a copy of the GNU General Public License along with
     14   GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 -->
     16 
     17 # On a phone, the cash keypad's own button is cut in half
     18 
     19 Take a cash payment on a phone-sized screen and the button that records it is
     20 drawn half off the bottom edge:
     21 
     22 ![The cash keypad on a phone, with the submit button clipped](images/cash-keypad-on-a-phone.png)
     23 
     24 That blue bar is **"Record ク10.00 cash"**, sliced through the middle of its
     25 text. It is the primary action of the screen, it is the only place the amount
     26 about to be recorded is spelled out in words, and the column it sits in does
     27 not scroll -- so there is no way to see the rest of it. The visible half can
     28 be tapped, which is the only reason this is not a dead end.
     29 
     30 Two things make it worse than a cosmetic clip:
     31 
     32 * The button carries **the amount**. A cashier about to record a cash payment
     33   is being asked to confirm a number they cannot fully read.
     34 * The line that says **"Change to return: ク3.00"** is below the fold in the
     35   right-hand column. Ten was handed over for a seven-unit bill and nothing on
     36   the visible screen says that three goes back. That column *is* scrollable,
     37   so the line can be reached -- but nothing suggests it is there.
     38 
     39 ## Why it happens
     40 
     41 `merchant-terminal/src/main/java/net/taler/merchantpos/checkout/CheckoutAmountEntry.kt`
     42 lays this screen out four ways. Three of them wrap their content in a
     43 `verticalScroll`. The phone-in-landscape branch is the one that does not:
     44 
     45 ```kotlin
     46 isLandscape ->
     47 {
     48     Row(
     49         modifier = Modifier.fillMaxSize().padding(horizontal = 24.dp, vertical = 20.dp),
     50         horizontalArrangement = Arrangement.spacedBy(36.dp),
     51         verticalAlignment = Alignment.Top,
     52     ) {
     53         CheckoutNumberPad(
     54             modifier = Modifier.weight(0.59f),     // <- no scroll, fixed heights
     55             keyHeight = 48.dp,
     56             keyGap = 8.dp,
     57             actionGap = 16.dp,
     58             …
     59         )
     60         Column(Modifier.weight(0.41f).fillMaxHeight().verticalScroll(rememberScrollState())) {
     61             AmountSummary(…)                        // <- this half does scroll
     62         }
     63     }
     64 }
     65 ```
     66 
     67 The keypad is a fixed stack and its height is arithmetic, not layout: four key
     68 rows at 48 dp, three 8 dp gaps, a 16 dp action gap and a 48 dp button, which
     69 is 280 dp, plus 40 dp of vertical padding -- 320 dp. A 1920x1080 phone at
     70 420 dpi is 411 dp high in landscape; the title row takes 64 dp and the status
     71 bar some more, leaving about 300 dp inside the `BoxWithConstraints`. The last
     72 20 dp of the button are simply past the edge, and since the column does not
     73 scroll they stay there.
     74 
     75 The tablet-landscape branch above it uses the same 48 dp keys and gets away
     76 with it, because a tablet is 800 dp high. Nothing in the phone branch
     77 recomputes the key size for a screen a third as tall.
     78 
     79 ## How it was found
     80 
     81 `checkout_cash_change_is_right` passes on a tablet. The same walk on a
     82 phone-sized worker reads the submit button at bounds `(392, 877, 737, 950)`
     83 in a window `954` pixels high, with no scrollable ancestor -- a control
     84 hanging over the bottom edge of the screen it is drawn on, which is the shape
     85 the harness photographs rather than reports as a label it could not find.
     86 
     87 ## Severity
     88 
     89 Medium. Nothing is lost and the sale can be completed: the top half of the
     90 button takes a tap. But the one screen in the app where a cashier counts money
     91 out of a till is the one that hides the amount and the change, and it does it
     92 on every phone-sized device, every time.
     93 
     94 ## Suggested fix
     95 
     96 `cash-keypad-submit-is-cut-off.diff`, verified on the emulator the screenshot
     97 came from. The key height is derived from the height actually available
     98 rather than fixed at 48 dp, and the column is given the same `verticalScroll`
     99 the other three branches already have as a backstop:
    100 
    101 ```kotlin
    102 val keyHeight =
    103     ((maxHeight - 40.dp - keyGap * 3 - actionGap - submitHeight) / 4)
    104         .coerceIn(36.dp, 48.dp)
    105 …
    106 CheckoutNumberPad(
    107     modifier = Modifier
    108         .weight(0.59f)
    109         .fillMaxHeight()
    110         .verticalScroll(rememberScrollState()),
    111     keyHeight = keyHeight,
    112     …
    113 )
    114 ```
    115 
    116 With it the button lands at `(392, 877, 737, 930)` -- inside the window, with
    117 its label whole. The keys lose a few dp, which is invisible beside a button
    118 that was not there.
    119 
    120 Not in the patch, because it is a judgement rather than a defect: **"Change to
    121 return"** still starts below the fold on the right. Moving it above the
    122 fraction shortcuts, or showing it beside the entered amount, would put the
    123 number a cashier needs where they are already looking.
    124 
    125 ## Reproducer
    126 
    127 ```bash
    128 POS_AVD_DEVICE=medium_phone POS_LCD_WIDTH=1920 POS_LCD_HEIGHT=1080 \
    129   POS_LCD_DENSITY=420 emu/emu.sh create 4
    130 emu/emu.sh boot 4 && emu/emu.sh prepare 4
    131 POS_WORKER=4 python3 driver/suite.py checkout_cash_change_is_right
    132 ```
    133 
    134 Turn Cash on in Settings -> Manage payment options first; the checkout does
    135 not exist while Taler is the only payment option.