| 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 |
¤tSetting, 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 |
|