contrib/bsdinstaller-1.1.6/docs/dfui/property.html

   1 <html>
   2 <head><title>DFUI: dfui_property</title></head>
   3 <body bgcolor="#ffffff">
   4
   5 <h1>dfui_property</h1>
   6
   7 <p><i>$Id: property.html,v 1.3 2005/02/15 21:56:23 cpressey Exp $</i></p>
   8
   9 <p>A <code>dfui_property</code> gives some information about an object
  10 which may or may not be present.</p>
  11
  12 <p>Properties may either be <i>weak</i>, meaning that frontends can ignore
  13 them and still be considered correct, or they may be <i>strong</i>, meaning
  14 that they carry with them a guarantee of behaviour, and any frontend which
  15 does not conform to that behaviour should be considered incorrect.  The vast
  16 majority of properties are weak.  Frontends are still encouraged to implement
  17 as many weak properties as apply to them, however, as they are used to help
  18 create a more pleasant and effective experience for the user.</p>
  19
  20 <h4>Form Properties</h4>
  21
  22 <table border=1>
  23 <tr><th>Hint Id</th><th>Description</th><th>Values</th></tr>
  24 <tr><td><code>role</code></td>
  25     <td>Allows the frontend to display a more meaningful form.</td>
  26     <td>
  27         <table>
  28         <tr><th>Value</th><th>Description</th><th>Assumptions</th></tr>
  29         <tr><td><code>menu</code></td>
  30           <td>Form is a menu, where the user may select one of a number of choices.</td>
  31           <td>Form has zero fields; form has more than one action.</td></tr>
  32         <tr><td><code>confirmation</code></td>
  33           <td>Form is a confirmation dialog box or similar, with a question and yes/no/etc choices.</td>
  34           <td>Form has zero fields; form has two or more actions.</td></tr>
  35         <tr><td><code>alert</code></td>
  36           <td>Form is there to display important information.</td>
  37           <td>Form has zero fields.</td></tr>
  38         </table>
  39     </td></tr>
  40 <tr><td><code>special</code></td>
  41     <td>Allows the frontend to display a special-purpose form for a particular occasion.
  42               These are typically unique forms used in only one application, such as the installer.</td>
  43     <td>
  44         <table>
  45         <tr><th>Value</th><th>Description</th><th>Assumptions</th></tr>
  46         <tr><td><code>bsdinstaller_welcome</code></td>
  47                 <td>Welcome screen for the BSD Installer.</td>
  48                 <td>TBA</td></tr>
  49         </table>
  50     </td></tr>
  51 <tr><td><code>minimum_width</code></td>
  52     <td>Suggests a minimum visual width of the form.</td>
  53     <td>
  54         Any integer.  The units of measurement are "em"'s, i.e.
  55         the width of the widest character in the typeface used to render the form.
  56     </td></tr>
  57 <tr><td><code>monospaced</code></td>
  58     <td>Suggests that the textual content of the form should be monospaced
  59         (i.e. each character should occupy the same width.)</td>
  60     <td>
  61         <code>true</code> or <code>false</code>, default <code>false</code>.
  62     </td></tr>
  63 <tr><td><code>default_action</code></td>
  64     <td>Specifies which action is the default (selected when the form is first displayed
  65            and/or triggered by the 'obvious thing' on the user's part, such as pressing Enter,
  66         depending on the interface.</td>
  67     <td>
  68         The id of an action on the form.
  69     </td></tr>
  70 </table>
  71
  72 <h4>Field Hints</h4>
  73
  74 <table border=1>
  75 <tr><th>Hint Id</th><th>Description</th><th>Values</th></tr>
  76 <tr><td><code>editable</code></td>
  77     <td>(<strong>STRONG</strong>) Determines whether the value(s) in this field may be edited by the user.</td>
  78     <td>
  79         <code>true</code> or <code>false</code>, default <code>true</code>.
  80     </td></tr>
  81 <tr><td><code>obscured</code></td>
  82     <td>(<strong>STRONG</strong>) Determines whether the user is allowed to observe the value(s) in this field.</td>
  83     <td>
  84         <code>true</code> or <code>false</code>, default <code>false</code>.
  85         Typically <code>true</code> is used for password-entry fields.
  86     </td></tr>
  87 <tr><td><code>control</code></td>
  88     <td>Allows the frontend to use a more meaningful widget.</td>
  89     <td>
  90         <table>
  91         <tr><th>Value</th><th>Description</th><th>Assumptions</th></tr>
  92         <tr><td><code>checkbox</code></td>
  93           <td>Field may be either 'on' or 'off' (a.k.a. 'yes' or 'no', 'true' or 'false').</td>
  94           <td>'on' is represented by the text <tt>Y</tt>, 'off' is represented by <tt>N</tt></td></tr>
  95         </table>
  96     </td></tr>
  97 <tr><td><code>prominence</code></td>
  98     <td>Indicates how prominent a particular field should be.</td>
  99     <td>
 100         <table>
 101         <tr><th>Value</th><th>Description</th><th>Assumptions</th></tr>
 102         <tr><td><code>minimal</code></td><td>Try to save space.  Typically means
 103         that an effort should be taken to save screen real estate by having
 104         the important contents of this field "drop down" or "pop up" when needed.  This
 105         is particularly germane for fields with more than zero options, but that need not be
 106         a strict assumption.</td><td>TBA</td></tr>
 107         <tr><td><code>maximal</code></td><td>Try to draw attention to this field.</td><td>TBA</td></tr>
 108         <tr><td><code>normal</code></td><td>No special prominence (default.)</td><td>TBA</td></tr>
 109         </table>
 110     </td></tr>
 111 <tr><td><code>regexp</code></td>
 112     <td>Describes the pattern of characters that values of the field should match.</td>
 113     <td>
 114         A basic regular expression (define??)  Some examples might be <code>^\d+$</code> to match
 115         a positive integer, and <code>^a.*z$</code> to match anything that starts with a and ends with z.
 116     </td></tr>
 117 <tr><td><code>alignment</code></td>
 118     <td>Indicates how data within the field should be aligned.</td>
 119     <td>
 120         <table>
 121         <tr><th>Value</th><th>Description</th><th>Assumptions</th></tr>
 122         <tr><td><code>left</code></td><td>Align to the left edge.</td><td>TBA</td></tr>
 123         <tr><td><code>right</code></td><td>Align to the right edge.</td><td>TBA</td></tr>
 124         <tr><td><code>center</code></td><td>Center the contents.</td><td>TBA</td></tr>
 125         </table>
 126     </td></tr>
 127 </table>
 128
 129 <h4>Action Hints</h4>
 130
 131 <table border=1>
 132 <tr><th>Hint Id</th><th>Description</th><th>Values</th></tr>
 133 <tr><td><code>visited</code></td>
 134     <td>Indicates that this action leads to a form which has already been filled-out, or a path
 135         of events which has already been taken.  Supplied purely as a navigation aid.</td>
 136     <td>
 137         <table>
 138         <tr><th>Value</th><th>Description</th><th>Assumptions</th></tr>
 139         <tr><td><code>true</code></td><td>Indicate to user that this action was already visited.</td><td>TBA</td></tr>
 140         </table>
 141     </td></tr>
 142 <tr><td><code>accelerator</code></td>
 143     <td>Specifies a keystroke which will trigger this action under normal circumstances.</td>
 144     <td>
 145         Any letter between <code>a</code> and <code>z</code>.
 146     </td></tr>
 147 </table>
 148
 149 </body>
 150 </html>