home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xaw / Dialog < prev    next >
Encoding:
Text File  |  1991-07-29  |  8.0 KB  |  305 lines
  1. .NH 2
  2. Dialog Widget
  3. .LP
  4. .XS
  5.     Dialog Widget
  6. .XE
  7. .IN "Dialog widget" "" "@DEF@"
  8. .Ds 0
  9. .TA 2.0i
  10. .ta 2.0i
  11. .sp
  12. Application Header file    <X11/Xaw/Dialog.h>
  13. .IN "Dialog.h" ""
  14. Class Header file    <X11/Xaw/DialogP.h>
  15. .IN "DialogP.h" ""
  16. Class        dialogWidgetClass
  17. .IN "dialogWidgetClass" ""
  18. Class Name    Dialog
  19. .IN "Dialog widget" "class name"
  20. Superclass    Form
  21. .sp
  22. .De
  23. .LP
  24. The Dialog widget implements a commonly used interaction semantic to
  25. prompt for auxiliary input from a user.  For example, you can use a
  26. Dialog widget when an application requires a small piece of information,
  27. such as a filename, from the user.  A Dialog widget, which is simply a
  28. special case of the Form widget, provides a convenient way to create a
  29. preconfigured form.
  30. .LP
  31. The typical Dialog widget contains three areas.  The first line
  32. contains a description of the function of the Dialog widget, for
  33. example, the string \fIFilename:\fP.  The second line contains an area
  34. into which the user types input.  The third line can contain buttons
  35. that let the user confirm or cancel the Dialog input.  Any of these
  36. areas may be omitted by the application.
  37. .NH 3
  38. Resources
  39. .LP
  40. When creating a Dialog widget instance, the following resources are
  41. retrieved from the argument list or the resource database:
  42. .IN "Dialog widget" "resources"
  43. .ps 9
  44. .nr PS 9
  45. .vs 11
  46. .nr VS 11
  47. .TS H
  48. lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
  49. _
  50. .sp 3p
  51. .TB
  52. Name    Class    Type    Notes    Default Value
  53. .sp 3p
  54. _
  55. .TH
  56. .R
  57. .sp 3p
  58. accelerators    Accelerators    AcceleratorTable        NULL
  59. ancestorSensitive    AncestorSensitive    Boolean    D    True
  60. background    Background    Pixel        XtDefaultBackground
  61. backgroundPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  62. borderColor    BorderColor    Pixel        XtDefaultForeground
  63. borderPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  64. borderWidth    BorderWidth    Dimension        1
  65. children    ReadOnly    WidgetList    R    NULL
  66. colormap    Colormap    Colormap        Parent's Colormap
  67. defaultDistance    Thickness    int        4
  68. depth    Depth    int    C    Parent's Depth
  69. destroyCallback    Callback    XtCallbackList        NULL
  70. height    Height    Dimension    A    Enough space to contain all children
  71. icon    Icon    Bitmap        None
  72. label    Label    String        "label"
  73. mappedWhenManaged    MappedWhenManaged    Boolean        True
  74. numChildren    ReadOnly    Cardinal    R    0
  75. screen    Screen    Screen    R    Parent's Screen
  76. sensitive    Sensitive    Boolean        True
  77. translations    Translations    TranslationTable        NULL
  78. value    Value    String        no value widget
  79. width    Width    Dimension    A    Enough space to contain all children
  80. x    Position    Position        0
  81. y    Position    Position        0
  82. .sp 3p
  83. _
  84. .TE
  85. .ps 11
  86. .nr PS 11
  87. .vs 13
  88. .nr VS 13
  89. .Ac
  90. .As
  91. .Bg
  92. .Gp
  93. .Bc
  94. .Bp
  95. .Bw
  96. .Ch
  97. .Cm
  98. .Dd
  99. .Dp
  100. .Dc
  101. .Hw
  102. .IP \fBicon\fP 1.5i
  103. A pixmap image to be displayed immediately to the left of the 
  104. Dialog widget's label.
  105. .IP \fBlabel\fP 1.5i
  106. A Latin1 string to be displayed at the top of the Dialog widget.
  107. .Mm
  108. .Nc
  109. .Sc
  110. .Se
  111. .Tr
  112. .IP \fBvalue\fP 1.5i
  113. An initial value for the string field that the user will enter text
  114. into.  By default, no text entry field is available to the user.
  115. Specifying an initial value for \fBvalue\fP activates the text entry
  116. field.  If string input is desired, but no initial value is to be
  117. specified then set this resource to "" (empty string).
  118. .Xy
  119. .NH 3
  120. Constraint Resources
  121. .LP
  122. .IN "Dialog widget" "constraint resources"
  123. Each child of the Dialog widget may request special layout resources
  124. be applied to it.  These \fIconstraint\fP resources allow the Dialog
  125. widget's children to specify individual layout requirements.
  126. .LP
  127. .ps 9
  128. .nr PS 9
  129. .vs 11
  130. .nr VS 11
  131. .TS H
  132. lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
  133. _
  134. .sp 3p
  135. .TB
  136. Name    Class    Type    Notes    Default Value
  137. .sp 3p
  138. _
  139. .TH
  140. .R
  141. .sp 3p
  142. bottom    Edge    XawEdgeType        XawRubber
  143. fromHoriz    Widget    Widget        NULL (left edge of Dialog)
  144. fromVert    Widget    Widget         NULL (top edge of Dialog)
  145. horizDistance    Thickness    int        \fBdefaultDistance\fP resource
  146. left    Edge    XawEdgeType        XawRubber
  147. .IN "XawEdgeType" ""
  148. resizable    Boolean    Boolean        FALSE
  149. right    Edge    XawEdgeType        XawRubber
  150. .IN "XawRubber" ""
  151. top    Edge    XawEdgeType        XawRubber
  152. vertDistance    Thickness    int        \fBdefaultDistance\fP resource
  153. .sp 3p
  154. _
  155. .TE
  156. .ps 11
  157. .nr PS 11
  158. .vs 13
  159. .nr VS 13
  160. .Bt
  161. .Fh
  162. .Hd
  163. .Rl
  164. .NH 3
  165. Layout Semantics
  166. .IN "Dialog widget" "layout semantics"
  167. .LP
  168. .Lt Dialog
  169. .LP
  170. .ps 9
  171. .nr PS 9
  172. .vs 11
  173. .nr VS 11
  174. .TS H
  175. lw(1.5i) lw(1i) lw(3i).
  176. _
  177. .sp 3p
  178. .TB
  179. Edge Type    Resource Name    Description
  180. .sp 3p
  181. _
  182. .TH
  183. .R
  184. .sp 3p
  185. XawChainBottom    ChainBottom    Edge remains a fixed distance from bottom of Dialog
  186. .IN "XawChainBottom" ""
  187. XawChainLeft    ChainLeft    Edge remains a fixed distance from left of Dialog
  188. .IN "XawChainLeft" ""
  189. XawChainRight    ChainRight    Edge remains a fixed distance from right of Dialog
  190. .IN "XawChainRight" ""
  191. XawChainTop    ChainTop    Edge remains a fixed distance from top of Dialog
  192. .IN "XawChainTop" ""
  193. XawRubber    Rubber    Edges will move a proportional distance
  194. .IN "XawRubber" ""
  195. .sp 3p
  196. _
  197. .TE
  198. .ps 11
  199. .nr PS 11
  200. .vs 13
  201. .nr VS 13
  202. .NH 4
  203. Example
  204. .LP
  205. If you wish to force the Dialog to never resize one or more of its children
  206. then set \fBleft\fP and \fBright\fP to \fBXawChainLeft\fP and
  207. \fBtop\fP and \fBbottom\fP to \fBXawChainTop\fP.  This will cause
  208. the child to remain a fixed distance from the top and left
  209. edges of the Dialog, and to never resize.
  210. .NH 4
  211. Special Considerations
  212. .IN "Dialog widget" "special considerations"
  213. .LP
  214. The Dialog widget automatically sets the \fBtop\fP and \fBbottom\fP
  215. resources for all Children that are subclasses of the Command widget,
  216. as well as the widget children that are used to contain the \fBlabel\fP,
  217. \fBvalue\fP, and \fBicon\fP.  This policy allows the buttons at the
  218. bottom of the Dialog to interact correctly with the predefined children,
  219. and makes it possible for a client to simply create and manage a new
  220. Command button without having to specify its constraints.
  221. .LP
  222. The Dialog will also set \fBfromLeft\fP to the last button in the
  223. .IN "fromLeft" ""
  224. Dialog for each new button added to the Dialog widget.
  225. .LP
  226. The automatically added constraints cannot be overridden, as they are
  227. policy decisions of the Dialog widget.  If a more flexible Dialog is
  228. desired, the application is free to use the Form widget to create its
  229. own Dialog policy. 
  230. .NH 3
  231. Automatically Created Children.
  232. .IN "Dialog widget" "automatically created children"
  233. .LP
  234. The Dialog uses Label widgets to contain the \fBlabel\fP and \fBicon\fP.
  235. These widgets are named \fIlabel\fP and \fIicon\fP respectively.  The
  236. Dialog \fBvalue\fP is contained in an AsciiText widget whose name is
  237. \fIvalue\fP.  Using \fBXtNameToWidget\fP the application can change
  238. .IN "XtNameToWidget" ""
  239. those resources associated with each of these widgets that are not
  240. available through the Dialog widget itself.
  241. .LP
  242. .NH 3
  243. Convenience Routines
  244. .LP
  245. To return the character string in the text field, use
  246. .PN XawDialogGetValueString .
  247. .IN "XawDialogGetValueString" "" "@DEF@"
  248. .FD 0
  249. String XawDialogGetValueString(\fIw\fP)
  250. .br
  251.     Widget \fIw\fP;
  252. .FN
  253. .IP \fIw\fP 1i
  254. Specifies the Dialog widget.
  255. .LP
  256. This function returns a copy of the value string of the Dialog
  257. widget.  This string is allocated by the AsciiText widget and will
  258. remain valid and unchanged until another call to
  259. \fBXawDialogGetValueString\fP or an \fBXtGetValues\fP call on the
  260. \fBvalue\fP widget, when the string will be automatically freed, and
  261. a new string is returned.  This string may be freed earlier by calling
  262. the function \fBXawAsciiSourceFreeString\fP.
  263. .IN "XawAsciiSourceFreeString" ""
  264. .LP
  265. .sp
  266. To add a new button to the Dialog widget use
  267. \fBXawDialogAddButton\fP.
  268. .IN "XawDialogAddButton" "" "@DEF@"
  269. .FD 0
  270. void XawDialogAddButton(\fIw\fP, \fIname\fP, \fIfunc\fP, \fIclient_data\fP)
  271. .br
  272.     Widget \fIw\fP;
  273. .br
  274.     String \fIname\fP;
  275. .br
  276.     XtCallbackProc \fIfunc\fP;
  277. .br
  278.     XtPointer \fIclient_data\fP;
  279. .FN
  280. .IP \fIw\fP 1i
  281. Specifies the Dialog widget.
  282. .IP \fIname\fP 1i
  283. Specifies the name of the new Command button to be added to the Dialog.
  284. .IP \fIfunc\fP 1i
  285. Specifies a callback function to be called when this button is activated.  If
  286. NULL is specified then no callback is added.
  287. .IP \fIclient_data\fP 1i
  288. Specifies the client_data to be passed to the \fIfunc\fP.
  289. .LP
  290. This function is merely a shorthand for the code sequence:
  291. .sp
  292. .ps 9
  293. .nr PS 9
  294. .Ds 0
  295. .TA 1i 2i
  296. .ta 1i 2i
  297. {
  298.     Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO);
  299.     XtAddCallback(button, XtNcallback, func, client_data);
  300. }
  301. .De
  302. .ps 11
  303. .nr PS 11
  304. .sp
  305.