1Writing on the braille display(3) BrlAPI Writing on the braille display(3)
2
6 Writing on the braille display - Write text to the braille display.
7 Data Structures
10 struct brlapi_writeArguments_t
11 Defines
13 #define BRLAPI_DISPLAY_DEFAULT -1
14 #define BRLAPI_CURSOR_LEAVE -1
15 #define BRLAPI_CURSOR_OFF 0
16 #define BRLAPI_WRITEARGUMENTS_INITIALIZER { BRLAPI_DISPLAY_DEFAULT,
17 0, 0, NULL, -1, NULL, NULL, BRLAPI_CURSOR_LEAVE, NULL }
18 Functions
20 int BRLAPI_STDCALL brlapi_writeText (int cursor, const char *text)
21 int BRLAPI_STDCALL brlapi__writeText (brlapi_handle_t *handle, int
22 cursor, const char *text)
23 int BRLAPI_STDCALL brlapi_writeDots (const unsigned char *dots)
24 int BRLAPI_STDCALL brlapi__writeDots (brlapi_handle_t *handle, const
25 unsigned char *dots)
26 int BRLAPI_STDCALL brlapi_write (const brlapi_writeArguments_t
27 *arguments)
28 int BRLAPI_STDCALL brlapi__write (brlapi_handle_t *handle, const
29 brlapi_writeArguments_t *arguments)
30
32 Once brlapi_enterTtyMode() was called, the application can call
33 brlapi_writeText() to write things on the braille display.
34 Note:
36 Be sure to call brlapi_enterTtyMode() before calling
37 brlapi_write(), or else you'll get an error. This is particularly
38 not always trivial when writing multithreaded applications.
39 Dots are coded as described in ISO/TR 11548-1: a dot pattern is
41 coded by a byte in which bit 0 is set iff dot 1 is up, bit 1 is set
42 iff dot 2 is up, ... bit 7 is set iff dot 8 is up. This also
43 corresponds to the low-order byte of the coding of unicode's
44 braille row U+2800.
45
47 #define BRLAPI_CURSOR_LEAVE -1
48 Do not change the cursor's state or position.
49 See also:
51 brlapi_writeText() brlapi_write() brlapi_writeArguments_t
52 #define BRLAPI_CURSOR_OFF 0
54 Do not display the cursor.
55 See also:
57 brlapi_writeText() brlapi_write() brlapi_writeArguments_t
58 #define BRLAPI_DISPLAY_DEFAULT -1
60 Write to the default display on the braille device.
61 See also:
63 brlapi_write() brlapi_writeArguments_t
64 #define BRLAPI_WRITEARGUMENTS_INITIALIZER { BRLAPI_DISPLAY_DEFAULT, 0, 0,
66 NULL, -1, NULL, NULL, BRLAPI_CURSOR_LEAVE, NULL }
67 Allows to initialize a structure of type brlapi_writeArguments_t * with
68 default values: displayNumber = BRLAPI_DISPLAY_DEFAULT; (unspecified)
69 regionBegin = regionSize = 0; (update the whole display, DEPRECATED and
70 will be forbidden in next release. You must always express the region
71 you wish to update) text = andMask = orMask = NULL; (no text, no
72 attribute) cursor = BRLAPI_CURSOR_LEAVE; (don't touch cursor)
73
75 int BRLAPI_STDCALL brlapi__write (brlapi_handle_t * handle, const
76 brlapi_writeArguments_t * arguments)
77 int BRLAPI_STDCALL brlapi__writeDots (brlapi_handle_t * handle, const
78 unsigned char * dots)
79 int BRLAPI_STDCALL brlapi__writeText (brlapi_handle_t * handle, int cursor,
80 const char * text)
81 int BRLAPI_STDCALL brlapi_write (const brlapi_writeArguments_t * arguments)
82 Update a specific region of the braille display and apply and/or masks
83 Parameters:
85 arguments gives information necessary for the update
86 regionBegin and regionSize must be filled for specifying which part of
88 the display will be updated, as well as the size (in characters, not
89 bytes) of the text, andMask and orMask members.
90 If given, the 'text' field holds the text that will be displayed in the
92 region. The char string must hold exactly as many characters as the
93 region fields express. For multibyte text, this is the number of
94 multibyte caracters. Notably, combining and double-width caracters
95 count for 1.
96 The actual length of the text in bytes may be specified thanks to
98 textSize. If -1 is given, it will be computed thanks to strlen(), so
99 'text' must then be a NUL-terminated string.
100 The 'andMask' and 'orMask' masks, if present, are then applied on top
102 of the text, one byte per character. This hence permits the
103 superimposing of attributes over the text. For instance, setting an
104 andMask mask full of
105 BRLAPI_DOT1|BRLAPI_DOT2|BRLAPI_DOT3|BRLAPI_DOT4|BRLAPI_DOT5|BRLAPI_DOT6
106 will only keep (logical AND) dots 1-6, hence dropping dots 7 and 8. On
107 the contrary, setting an orMask full of BRLAPI_DOT7|BRLAPI_DOT8 will
108 add (logical OR) dots 7 and 8.
109 The 'charset' field, if present, specifies the charset of the 'text'
111 field. If it is '', the current locale's charset (if any) is assumed.
112 Else, the 8-bit charset of the server is assumed.
113 A special invocation is with an unmodified initialized structure: this
115 clears the client's whole display, letting the display of other
116 applications on the same tty or of applications 'under' the tty appear.
117 See Concurrency management section of the BrlAPI documentation for more
118 details.
119 Returns:
121 0 on success, -1 on error.
122 int BRLAPI_STDCALL brlapi_writeDots (const unsigned char * dots)
124 Write the given dots array to the display
125 Parameters:
127 dots points on an array of dot information, one per character. Its
128 size must hence be the same as what brlapi_getDisplaySize()
129 returns.
130 Returns:
132 0 on success, -1 on error.
133 int BRLAPI_STDCALL brlapi_writeText (int cursor, const char * text)
135 Write the given \0-terminated string to the braille display
136 If the string is too long, it is cut. If it's too short, spaces are
138 appended. The current LC_CTYPE locale is considered, unless it is left
139 as default 'C', in which case the charset is assumed to be 8bits, and
140 the same as the server's.
141 Parameters:
143 cursor gives the cursor position; if equal to BRLAPI_CURSOR_OFF, no
144 cursor is shown at all; if cursor==BRLAPI_CURSOR_LEAVE, the cursor
145 is left where it is
146 text points to the string to be displayed.
147 Returns:
149 0 on success, -1 on error.
150Version 1.0 4 Jun 2007 Writing on the braille display(3)