vty-6.1: A simple terminal UI library

Safe Haskell | Safe-Inferred
Language | Haskell2010

Graphics.Vty.UnicodeWidthTable.Install

Synopsis

- data TableInstallException
  - = TableInitFailure Int Int
  - | TableRangeFailure Int WidthTableRange
  - | TableActivationFailure Int
- installUnicodeWidthTable :: UnicodeWidthTable -> IO ()
- isCustomTableReady :: IO Bool

# Documentation

data TableInstallException Source #

Exception type raised by `installUnicodeWidthTable`.

Constructors

TableInitFailure Int Int | The width table could not be initialized. Args: failure status, requested table size.
TableRangeFailure Int WidthTableRange | A code point range could not be configured. Args: failure status, offending range.
TableActivationFailure Int | The table could not be activated. Args: failure status.

#### Instances

Instances details

Exception TableInstallException Source # |
Instance details Defined in Graphics.Vty.UnicodeWidthTable.Install Methods toException :: TableInstallException -> SomeException Source # fromException :: SomeException -> Maybe TableInstallException Source # displayException :: TableInstallException -> String Source #
Show TableInstallException Source # |
Instance details Defined in Graphics.Vty.UnicodeWidthTable.Install Methods showsPrec :: Int -> TableInstallException -> ShowS Source # show :: TableInstallException -> String Source # showList :: [TableInstallException] -> ShowS Source #
Eq TableInstallException Source # |
Instance details Defined in Graphics.Vty.UnicodeWidthTable.Install Methods (==) :: TableInstallException -> TableInstallException -> Bool Source # (/=) :: TableInstallException -> TableInstallException -> Bool Source #

installUnicodeWidthTable :: UnicodeWidthTable -> IO () Source #

Install a custom unicode character width table. Such tables are obtained with `buildUnicodeWidthTable` and `readUnicodeWidthTable`.

ALERT! This function is probably not what you want to use because it is automatically called by `mkVty`. You will only ever need to call this function if you want to use functions in `Width` without controlling the terminal with `mkVty`.

This affects the behavior of the `wcwidth` function and functions that call it. It does so by changing global state available to the C implementation of `wcwidth`. To ensure that your program gets consistent results from evaluating calls to `wcwidth`, the installation of a custom table should be performed before you call `wcwidth` in your program.

This is best done at Vty startup, and if you use `mkVty`, that function calls this automatically based on the Vty configuration's declared width tables. It is exposed as part of the public API so that applications can call this as needed if they don't want to control the terminal with `mkVty` but do want to make calls to `wcwidth`.

It's also important to note that once a custom table has been installed, it is permanent for the life of the process. No new table can be installed, and the new custom table cannot be removed.

If this function fails for any reason -- if the table cannot be installed or is invalid, or if a custom table already exists -- this will raise a `TableInstallException` exception.

This function is thread-safe.

isCustomTableReady :: IO Bool Source #

Returns True if and only if a custom table has been allocated and marked as ready for use.

This function is thread-safe.