Graphics.Vty.UnicodeWidthTable.Install

Documentation

data TableInstallException

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

Exception TableInstallException

Defined in Graphics.Vty.UnicodeWidthTable.Install

Methods

toException :: TableInstallException -> SomeException

fromException :: SomeException -> Maybe TableInstallException

displayException :: TableInstallException -> String

Show TableInstallException

Defined in Graphics.Vty.UnicodeWidthTable.Install

Methods

showsPrec :: Int -> TableInstallException -> ShowS

show :: TableInstallException -> String

showList :: [TableInstallException] -> ShowS

Eq TableInstallException

Defined in Graphics.Vty.UnicodeWidthTable.Install

Methods

(==) :: TableInstallException -> TableInstallException -> Bool

(/=) :: TableInstallException -> TableInstallException -> Bool

installUnicodeWidthTable :: UnicodeWidthTable -> IO ()

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

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

This function is thread-safe.