Debian Codegraph @

Drivers/Braille/DotPad/README

raw
1 The DotPad Braille Driver
2 =========================
3
4 .. contents::
5
6 Driver Properties
7 -----------------
8
9 There are a number of properties which control how the driver renders text.
10 Each of these:
11
12 * has a built-in default.
13 * can have its built-in default overridden via a driver parameter.
14 * can be changed and queried at run-time via BrlAPI.
15
16 .. topic:: Specifying a Driver Parameter
17
18 The general format of a driver parameter specification is::
19
20 [driver:]name=value
21
22 The name, as well as the value (if it's a word), can be abbreviated.
23 The optional *driver* component is the two-letter code
24 of the driver whose parameter is being specified.
25 It's a good idea to include it in order to avoid
26 any ambiguity with the names of the parameters of other drivers.
27 The DotPad's driver code is ``dp``.
28
29 In decreasing order of precedence, the parameter can be specified via:
30
31 * The ``--braille-parameters=`` (``-B``) command line option.
32 * The ``BRLTTY_BRAILLE_PARAMETERS`` environment variable (if enabled).
33 * The ``braille-parameters`` configuration directive.
34
35 .. topic:: Changing a Driver Property
36
37 A driver property is changed by setting the ``DRIVER_PROPERTY_VALUE`` BrlAPI parameter.
38 This is done by calling the ``brlapi_setParameter()`` function
39 with its ``subparam`` argument set to the driver property.
40 The DotPad's driver properties are defined within the ``brldefs-dp.h`` header.
41
42 To set the display to the graphic area, for example, you'd do::
43
44 brlapi_param_t parameter = BRLAPI_PARAM_DRIVER_PROPERTY_VALUE;
45 brlapi_param_subparam_t subparam = DP_SELECT_DISPLAY;
46 brlapi_param_flags_t flags = 0;
47 brlapi_param_driverPropertyValue_t newSetting = DP_DISPLAY_GRAPHIC;
48 int result = brlapi_setParameter(
49 parameter, subparam, flags,
50 &newSetting, sizeof(newSetting)
51 );
52
53 .. topic:: Querying a Driver Property
54
55 Querying a driver property is similar to changing it (see above), except that:
56
57 * You call the ``brlapi_getParameter()`` function.
58 * The property's current value is returned within the data area.
59
60 To query the display property, for example, you'd do::
61
62 brlapi_param_t parameter = BRLAPI_PARAM_DRIVER_PROPERTY_VALUE;
63 brlapi_param_subparam_t subparam = DP_SELECT_DISPLAY;
64 brlapi_param_flags_t flags = 0;
65 brlapi_param_driverPropertyValue_t currentSetting;
66 ssize_t length = brlapi_getParameter(
67 parameter, subparam, flags,
68 &currentSetting, sizeof(currentSetting)
69 );
70
71 Display Selection
72 ~~~~~~~~~~~~~~~~~
73
74 Select whether text is written to the text area or to the graphic area.
75 If text is written to the graphic area then a multi-line display is emulated.
76
77 The driver parameter is ``display=``.
78 It can be set to one of the following:
79
80 ``default``
81 Use the graphic area if the device has one,
82 else use the text area.
83
84 ``text``
85 Explicitly use the text area.
86 It's an error if the device doesn't have one.
87
88 ``graphic``
89 Explicitly use the graphic area.
90 It's an error if the device doesn't have one.
91
92 The driver property is ``DP_SELECT_DISPLAY``.
93 It can be set to one of the following:
94
95 ``DP_DISPLAY_TEXT``
96 Switch to the text area.
97 It's an error if the device doesn't have one.
98
99 ``DP_DISPLAY_GRAPHIC``
100 Switch to the graphic area.
101 It's an error if the device doesn't have one.
102
103 Status Cells
104 ~~~~~~~~~~~~
105
106 When emulating a multi-line display within the graphic area,
107 specify whether or not status information is to be written to the actual text area.
108 The default is to write it.
109
110 The driver parameter is ``statusCells=``.
111 It may be specified as either ``yes`` (the default) or as ``no``.
112
113 The driver property is ``DP_STATUS_CELLS``.
114 It may be set to either 0 for ``no`` or to 1 for ``yes``.
115
116 Horizontal Spacing
117 ~~~~~~~~~~~~~~~~~~
118
119 When emulating a multi-line display within the graphic area,
120 specify how many columns of dots separate the characters from one another.
121 It must be an integer within the range 0-10 (inclusive).
122 The default is 1.
123
124 The driver parameter is ``horizontalSpacing=``.
125
126 The driver property is ``DP_HORIZONTAL_SPACING``.
127
128 Vertical Spacing
129 ~~~~~~~~~~~~~~~~
130
131 When emulating a multi-line display within the graphic area,
132 specify how many rows of dots separate the lines from one another.
133 It must be an integer within the range 0-10 (inclusive).
134 The default is 2.
135
136 The driver parameter is ``verticalSpacing=``.
137
138 The driver property is ``DP_VERTICAL_SPACING``.
139