home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xaw / Paned < prev    next >
Encoding:
Text File  |  1991-07-31  |  16.8 KB  |  515 lines
  1. .NH 2 
  2. Paned Widget
  3. .LP
  4. .XS
  5.     Paned Widget
  6. .XE
  7. .IN "Paned widget" "" "@DEF@"
  8. .Ds 0
  9. .TA 2.0i
  10. .ta 2.0i
  11. .sp
  12. Application Header file    <X11/Xaw/Paned.h>
  13. .IN "Paned.h" ""
  14. Class Header file    <X11/Xaw/PanedP.h>
  15. .IN "PanedP.h" ""
  16. Class        panedWidgetClass
  17. .IN "panedWidgetClass" ""
  18. Class Name    Paned
  19. .IN "Paned widget" "class name"
  20. Superclass    Constraint
  21. .sp
  22. .De
  23. .LP
  24. The Paned widget manages children in a vertically or horizontally
  25. tiled fashion.  The panes may be dynamically resized by the user by
  26. using the \fIgrips\fP that appear near the right or bottom edge of the
  27. border between two panes.
  28. .LP
  29. The Paned widget may accept any widget class as a pane \fBexcept\fP
  30. Grip.  Grip widgets have a special meaning for the Paned widget, and
  31. adding a Grip as its own pane will confuse the Paned widget.
  32. .NH 3
  33. Using the Paned widget.
  34. .IN "Paned widget" "using"
  35. .LP
  36. The grips allow the panes to be resized by the user.  The semantics of
  37. how these panes resize is somewhat complicated, and warrants further
  38. explanation here.  When the mouse pointer is positioned on a grip and
  39. pressed, an arrow is displayed that indicates the pane that is to be to
  40. be resized.  While keeping the mouse button down, the user can move the
  41. grip up and down (or left and right).  This, in turn, changes the size
  42. of the pane.  The size of the Paned widget will not change.   Instead,
  43. it chooses another pane (or panes) to resize. For more details on which
  44. pane it chooses to resize, see \fBLayout Semantics\fP.
  45. .LP
  46. One pointer binding allows the border between two panes to be moved,
  47. without affecting any of the other panes.  When this occurs the pointer
  48. will change to an arrow that points along the pane border.
  49. .LP
  50. The default bindings for the Paned widget's grips are:
  51. .ps 9
  52. .nr PS 9
  53. .vs 11
  54. .nr VS 11
  55. .TS H
  56. lw(1i) lw(2i) lw(2i).
  57. _
  58. .sp 3p
  59. .TB
  60. Mouse button    Pane to Resize - Vertical    Pane to Resize - Horizontal
  61. .sp 3p
  62. _
  63. .TH
  64. .R
  65. .sp 3p
  66. 1 (left)    above the grip    left of the grip
  67. 2 (middle)    adjust border    adjust border
  68. 3 (right)    below the grip    right of the grip
  69. .sp 3p
  70. _
  71. .TE
  72. .ps 11
  73. .nr PS 11
  74. .vs 13
  75. .nr VS 13
  76. .NH 3
  77. Resources
  78. .LP
  79. When creating a Paned widget instance, the following resources are
  80. retrieved from the argument list or the resource database:
  81. .LP
  82. .IN "Paned widget" "resources"
  83. .ps 9
  84. .nr PS 9
  85. .vs 11
  86. .nr VS 11
  87. .TS H
  88. lw(1i) lw(1i) lw(1i) lw(.4i) lw(2i).
  89. _
  90. .sp 3p
  91. .TB
  92. Name    Class    Type    Notes    Default Value
  93. .sp 3p
  94. _
  95. .TH
  96. .R
  97. .sp 3p
  98. accelerators    Accelerators    AcceleratorTable        NULL
  99. ancestorSensitive    AncestorSensitive    Boolean    D    True
  100. background    Background    Pixel        XtDefaultBackground
  101. backgroundPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  102. betweenCursor    Cursor    Cursor    A    Depends on orientation
  103. borderColor    BorderColor    Pixel        XtDefaultForeground
  104. borderPixmap    Pixmap    Pixmap        XtUnspecifiedPixmap
  105. borderWidth    BorderWidth    Dimension        1
  106. children    ReadOnly    WidgetList    R    NULL
  107. colormap    Colormap    Colormap        Parent's Colormap
  108. cursor    Cursor    Cursor        None
  109. depth    Depth    int    C    Parent's Depth
  110. destroyCallback    Callback    XtCallbackList        NULL
  111. gripCursor    Cursor    Cursor    A    Depends on orientation
  112. gripIndent    GripIndent    Position        10
  113. gripTranslations    Translations    TranslationTable        see below
  114. height    Height    Dimension    A    Depends on orientation
  115. horizontalBetweenCursor    Cursor    Cursor        sb_up_arrow
  116. horizontalGripCursor    Cursor    Cursor        sb_h_double_arrow
  117. internalBorderColor    BorderColor    Pixel        XtDefaultForeground
  118. internalBorderWidth    BorderWidth    Dimension        1
  119. leftCursor    Cursor    Cursor        sb_left_arrow
  120. lowerCursor    Cursor    Cursor        sb_down_arrow
  121. mappedWhenManaged    MappedWhenManaged    Boolean        True
  122. numChildren    ReadOnly    Cardinal    R    0
  123. orientation    Orientation    Orientation        XtorientVertical
  124. refigureMode    Boolean    Boolean        True
  125. rightCursor    Cursor    Cursor        sb_right_arrow
  126. screen    Screen    Screen    R    Parent's Screen
  127. sensitive    Sensitive    Boolean        True
  128. translations    Translations    TranslationTable        NULL
  129. upperCursor    Cursor    Cursor        sb_up_arrow
  130. verticalBetweenCursor    Cursor    Cursor        sb_left_arrow
  131. verticalGripCursor    Cursor    Cursor        sb_v_double_arrow
  132. width    Width    Dimension    A    Depends on orientation
  133. x    Paned    Position        0
  134. y    Paned    Position        0
  135. .sp 3p
  136. _
  137. .TE
  138. .ps 11
  139. .nr PS 11
  140. .vs 13
  141. .nr VS 13
  142. .Ac
  143. .As
  144. .Bg
  145. .Gp
  146. .Bc
  147. .Bp
  148. .Bw
  149. .Ch
  150. .Cm
  151. .IP \fBcursor\fP 1.5i
  152. The cursor to use when the mouse pointer is over the Paned widget, but
  153. not in any of its children (children may also inherit this cursor).  It
  154. should be noted that the internal borders are actually part of the Paned
  155. widget, not the children.
  156. .Dp
  157. .Dc
  158. .IP \fBgripCursor\fP 1.5i
  159. The cursor to use when the grips are not active.  The default value is
  160. \fBverticalGripCursor\fP or \fBhorizontalGripCursor\fP depending on
  161. the orientation of the Paned widget. 
  162. .IP \fBgripIndent\fP 1.5i
  163. The amount of space left between the right (or bottom) edge of the
  164. Paned widget and all the grips.
  165. .IP \fBgripTranslation\fP 1.5i
  166. Translation table that will be applied to all grips.
  167. .Hw
  168. .IP \fBhorizontalBetweenCursor\fP 1.5i
  169. .br
  170. .ns
  171. .IP \fBverticalBetweenCursor\fP 1.5i
  172. The cursor to be used for the grip when changing the boundary between
  173. two panes.  These resources allow the cursors to be different
  174. depending on the orientation of the Paned widget.
  175. .IP \fBhorizontalGripCursor\fP 1.5i
  176. .br
  177. .ns
  178. .IP \fBverticalGripCursor\fP 1.5i
  179. The cursor to be used for the grips when they are not active. These
  180. resources allow the cursors to be different depending on the
  181. orientation of the Paned widget. 
  182. .IP \fBinternalBorderColor\fP 1.5i
  183. A pixel value which indexes the widget's colormap to derive the internal
  184. border color of the widget's window.  The class name of this resource
  185. allows \fIPaned*BorderColor: blue\fP to set the internal border color
  186. for the Paned widget.  An optimization is invoked if
  187. \fBinternalBorderColor\fP and \fBbackground\fP are the same, and the
  188. internal borders are not drawn.  \fBinternalBorderWidth\fP is still left
  189. between the panes, however.
  190. .IP \fBinternalBorderWidth\fP 1.5i
  191. The width of the internal borders.  This is the amount of space left
  192. between the panes.  The class name of this resource allows
  193. \fIPaned*BorderWidth: 3\fP to set the internal border width for the
  194. Paned widget.
  195. .IP \fBleftCursor\fP 1.5i
  196. .br
  197. .ns
  198. .IP \fBrightCursor\fP 1.5i
  199. The cursor used to indicate which is the \fIimportant\fP pane to resize
  200. when the Paned widget is oriented horizontally.
  201. .IP \fBlowerCursor\fP 1.5i
  202. .br
  203. .ns
  204. .IP \fBupperCursor\fP 1.5i
  205. The cursor used to indicate which is the \fIimportant\fP pane to resize
  206. when the Paned widget is oriented vertically.
  207. .Mm
  208. .Nc
  209. This is not the same as the number of panes, since this also contains a
  210. grip for some of the panes, use \fBXawPanedGetNumSub\fP to retrieve the
  211. number of panes.
  212. .IP \fBorientation\fP 1.5i
  213. The orientation to stack the panes.  This value can be either
  214. \fBXtorientVertical\fP or \fBXtorientHorizontal\fP.
  215. .IN "XtorientVertical" ""
  216. .IN "XtorientHorizontal" ""
  217. .IN "conversions" "Orientation"
  218. .Rs "vertical \fPand\fB horizontal"
  219. .IP \fBrefigureMode\fP 1.5i
  220. This resource allows pane layout to be suspended.  If this value is
  221. \fBFalse\fP, then no layout actions will be taken.  This may improve
  222. efficiency when adding or removing more than one pane from the Paned
  223. widget.
  224. .Sc
  225. .Se
  226. .Tr
  227. .Xy
  228. .NH 3
  229. Constraint Resources
  230. .LP
  231. .IN "Paned widget" "constraint resources"
  232. Each child of the Paned widget may request special layout resources
  233. be applied to it.  These \fIconstraint\fP resources allow the Paned
  234. widget's children to specify individual layout requirements.
  235. .LP
  236. .ps 9
  237. .nr PS 9
  238. .vs 11
  239. .nr VS 11
  240. .TS H
  241. lw(1i) lw(1i) lw(1i) lw(.5i) lw(2i).
  242. _
  243. .sp 3p
  244. .TB
  245. Name    Class    Type    Notes    Default Value
  246. .sp 3p
  247. _
  248. .TH
  249. .R
  250. .sp 3p
  251. allowResize    Boolean    Boolean        False
  252. max    Max    Dimension        Infinity
  253. min    Min    Dimension        Height of Grips
  254. preferredPaneSize    PreferredPaneSize    Dimension        ask child
  255. resizeToPreferred    Boolean    Boolean        False
  256. showGrip    ShowGrip    Boolean        True
  257. skipAdjust    Boolean    Boolean        False
  258. .sp 3p
  259. _
  260. .TE
  261. .ps 11
  262. .nr PS 11
  263. .vs 13
  264. .nr VS 13
  265. .IP \fBallowResize\fP 1.5i
  266. If this value is \fBFalse\fP the the Paned widget will disallow all
  267. geometry requests from this child.
  268. .IP \fBmax\fP 1.5i
  269. .br
  270. .ns
  271. .IP \fBmin\fP 1.5i
  272. The absolute maximum or minimum size for this pane.  These values will
  273. never be overridden by the Paned widget.  This may cause some panes to be
  274. pushed off the bottom (or right) edge of the paned widget.
  275. .IP \fBpreferredPaneSize\fP 1.5i
  276. Normally the paned widget makes a QueryGeometry call on a child to
  277. determine the preferred size of the child's pane.  There are times
  278. when the application programmer or the user has a better idea of the
  279. preferred size of a pane.  Setting this resource causes the value
  280. passed to be interpreted as the preferred size, in pixels, of this pane.
  281. .IP \fBresizeToPreferred\fP 1.5i
  282. Determines whether or not to resize each pane to its preferred size
  283. when the Paned widget is resized.  See \fBLayout Semantics\fP for details.
  284. .IP \fBshowGrip\fP 1.5i
  285. If \fBTrue\fP then a grip will be shown for this pane.  The grip
  286. associated with a pane is either below or to the right of the pane.  No
  287. grip is ever shown for the last pane.
  288. .IP \fBskipAdjust\fP 1.5i
  289. This resource is used to determine which pane is forced to be resized.
  290. Setting this value to \fBTrue\fP makes this pane less likely to be
  291. forced to be resized.  See \fBLayout Semantics\fP for details.
  292. .NH 3
  293. Layout Semantics
  294. .LP
  295. .IN "Paned widget" "layout semantics"
  296. In order to make effective use of the Paned widget it is helpful to know
  297. the rules it uses to determine which child will be resized in any given
  298. situation.  There are three rules used to determine which child is
  299. resized.  While these rules are always the same, the panes that are
  300. searched can change depending upon what caused the relayout.
  301. .LP
  302. .sp
  303. \fBLayout Rules\fP
  304. .IP \fB1\fP .5i
  305. Do not let a pane grow larger than its \fBmax\fP or smaller than its
  306. \fBmin\fP.
  307. .IP \fB2\fP .5i
  308. Do not adjust panes with \fBskipAdjust\fP set.
  309. .IP \fB3\fP .5i
  310. Do not adjust panes away from their preferred size, although moving one
  311. closer to its preferred size is fine.
  312. .LP
  313. When searching the children the Paned widget looks for panes that
  314. satisfy all the rules, and if unsuccessful then it eliminates rule 3
  315. and then 2.  Rule 1 is always enforced. 
  316. .LP
  317. If the relayout is due to a resize or change in management then the
  318. panes are searched from bottom to top.  If the relayout is due to grip
  319. movement then they are searched from the grip selected in the direction
  320. opposite the pane selected.
  321. .NH 4
  322. Resizing Panes from a Grip Action
  323. .LP
  324. The pane above the grip is resized by invoking the GripAction with 
  325. \fBUpLeftPane\fP specified.  The panes below the grip are each checked
  326. against all rules, then rules 2 and 1 and finally against rule 1 only.
  327. No pane above the chosen pane will ever be resized.
  328. .LP
  329. The pane below the grip is resized by invoking the GripAction with 
  330. \fBLowRightPane\fP specified.  The panes above the grip are each
  331. checked in this case.  No pane below the chosen pane will ever be resized.
  332. .LP
  333. Invoking GripAction with \fBThisBorderOnly\fP specified just moves the
  334. border between the panes.  No other panes are ever resized.
  335. .NH 4
  336. Resizing Panes after the Paned widget is resized.
  337. .LP
  338. When the Pane widget is resized it must determine a new size for each
  339. pane.  There are two methods of doing this.  The Paned widget can either
  340. give each pane its preferred size and then resize the panes to fit, or
  341. it can use the current sizes and then resize the panes to fit.  The
  342. \fBresizeToPreferred\fP resource allows the application to tell the
  343. Paned widget whether to query the child about its preferred size
  344. (subject to the the \fBpreferredPaneSize\fP) or to use the current size
  345. when refiguring the pane locations after the pane has been resized.
  346. .LP
  347. There is one special case.  All panes assume they should resize to
  348. their preferred size until the Paned widget becomes visible to the user. 
  349. .NH 4
  350. Managing Children and Geometry Management
  351. .LP
  352. The Paned widget always resizes its children to their preferred sizes when
  353. a new child is managed, or a geometry management request is honored.
  354. The Paned widget will first attempt to resize itself to contain its
  355. panes exactly.  If this is not possible then it will hunt through the
  356. children, from bottom to top (right to left), for a pane to resize.
  357. .NH 4
  358. Special Considerations
  359. .LP
  360. When a user resizes a pane with the grips, the Paned widget assumes that
  361. this new size is the preferred size of the pane.
  362. .NH 3
  363. Grip Translations
  364. .LP
  365. The Paned widget has no action routines of its own, as all actions are
  366. handled through the grips.  The grips are each assigned a default
  367. Translation table.
  368. .LP
  369. .sp
  370. .Ds 0
  371. .TA .5i 2.25i
  372. .ta .5i 2.25i
  373.     <Btn1Down>:    GripAction(Start, UpLeftPane)
  374. .IN "GripAction" ""
  375.     <Btn2Down>:    GripAction(Start, ThisBorderOnly)
  376.     <Btn3Down>:    GripAction(Start, LowRightPane) 
  377.     <Btn1Motion>:    GripAction(Move, UpLeftPane) 
  378.     <Btn2Motion>:    GripAction(Move, ThisBorderOnly) 
  379.     <Btn3Motion>:    GripAction(Move, LowRightPane)
  380.     Any<BtnUp>:    GripAction(Commit)
  381. .De
  382. .sp
  383. .LP
  384. The Paned widget interprets the \fBGripAction\fP as taking two arguments.
  385. .IN "GripAction" ""
  386. The first argument may be any of the following:
  387. .IP \fBStart\fP 1i
  388. Sets up the Paned widget for resizing and changes the cursor of the
  389. grip.  The second argument determines which pane will be resized, and
  390. can take on any of the three values shown above.
  391. .IP \fBMove\fP 1i
  392. The internal borders are drawn over the current pane locations to
  393. animate where the borders would actually be placed if you were to move
  394. this border as shown.  The second argument must match the second argument
  395. that was passed to the \fBStart\fP action, that began this process.  If
  396. these arguments are not passed, the behavior is undefined.
  397. .IP \fBCommit\fP 1i
  398. This argument causes the Paned widget to commit the changes selected
  399. by the previously started action.  The cursor is changed back to the
  400. grip's inactive cursor.  No second argument is needed in this case.
  401. .NH 3 
  402. Convenience Routines
  403. .LP
  404. .IN "Paned widget" "enable pane resizing"
  405. .IN "Paned widget" "disable pane resizing"
  406. To enable or disable a child's request for pane resizing,
  407. use
  408. .PN XawPanedAllowResize :
  409. .IN "XawPanedAllowResize" "" "@DEF@"
  410. .FD 0
  411. void XawPanedAllowResize(\fIw\fP, \fIallow_resize\fP)
  412. .br
  413.      Widget \fIw\fP;
  414. .br
  415.      Boolean \fIallow_resize\fP;
  416. .FN
  417. .IP \fIw\fP 1i
  418. Specifies the child pane.
  419. .IP \fIallow_resize\fP
  420. Specifies whether or not resizing requests for this child will be
  421. granted by the Paned widget.
  422. .LP
  423. If allow_resize is \fBTrue\fP, the Paned widget allows geometry
  424. requests from the child to change the pane's height. If allow_resize
  425. is \fBFalse\fP, the Paned widget ignores geometry requests from the
  426. child to change the pane's height. The default state is \fBTrue\fP
  427. before the Pane is realized and \fBFalse\fP after it is realized.
  428. This procedure is equivalent to changing the \fBallowResize\fP
  429. constraint resource for the child.
  430. .LP
  431. .sp
  432. .IN "Paned widget" "change height settings"
  433. To change the minimum and maximum height settings for a pane, use
  434. .PN XawPanedSetMinMax :
  435. .IN "XawPanedSetMinMax" "" "@DEF@"
  436. .FD 0
  437. void XawPanedSetMinMax(\fIw\fP, \fImin\fP, \fImax\fP)
  438. .br
  439.      Widget \fIw\fP;
  440. .br
  441.      int \fImin\fP, \fImax\fP;   
  442. .FN
  443. .IP \fIw\fP 1i
  444. Specifies the child pane.
  445. .IP \fImin\fP 1i
  446. Specifies the new minimum height of the child, expressed in pixels.
  447. .IP \fImax\fP 1i
  448. Specifies new maximum height of the child, expressed in pixels.
  449. .LP
  450. This procedure is equivalent to setting the \fBmin\fP and \fBmax\fP
  451. constraint resources for the child.
  452. .LP
  453. .sp
  454. .IN "Paned widget" "get height settings"
  455. To retrieve the minimum and maximum height settings for a pane, use
  456. .PN XawPanedGetMinMax :
  457. .IN "XawPanedGetMinMax" "" "@DEF@"
  458. .FD 0
  459. void XawPanedGetMinMax(\fIw\fP, \fImin_return\fP, \fImax_return\fP)
  460. .br
  461.      Widget \fIw\fP;
  462. .br
  463.      int \fI*min_return\fP, \fI*max_return\fP;
  464. .FN
  465. .IP \fIw\fP 1i
  466. Specifies the child pane.
  467. .IP \fImin_return\fP 1i
  468. Returns the minimum height of the child, expressed in pixels.
  469. .IP \fImax_return\fP 1i
  470. Returns the maximum height of the child, expressed in pixels.
  471. .LP
  472. This procedure is equivalent to getting the \fBmin\fP and \fBmax\fP
  473. resources for this child child.
  474. .LP
  475. .sp
  476. .IN "Paned widget" "enable auto-reconfiguring"
  477. .IN "Paned widget" "disable auto-reconfiguring"
  478. To enable or disable automatic recalculation of pane sizes and positions,
  479. use 
  480. .PN XawPanedSetRefigureMode :
  481. .IN "XawPanedSetRefigureMode" "" "@DEF@"
  482. .FD 0
  483. void XawPanedSetRefigureMode(\fIw\fP, \fImode\fP)
  484. .br
  485.      Widget \fIw\fP;
  486. .br
  487.      Boolean \fImode\fP;
  488. .FN
  489. .IP \fIw\fP 1i
  490. Specifies the Paned widget.
  491. .IP \fImode\fP 1i
  492. Specifies whether the layout of the Paned widget is enabled (\fBTrue\fP)
  493. or disabled (\fBFalse\fP).
  494. .LP
  495. When making several changes to the children of a Paned widget
  496. after the Paned has been realized, it is a good idea to disable
  497. relayout until after all changes have been made.
  498. .LP
  499. .sp
  500. .IN "Paned widget" "getting the number of children"
  501. To retrieve the number of panes in a paned widget use
  502. \fBXawPanedGetNumSub\fP:
  503. .IN "XawPanedGetNumSub" "" "@DEF@"
  504. .FD 0
  505. int XawPanedGetNumSub(\fIw\fP)
  506. .br
  507.      Widget \fIw\fP;
  508. .FN
  509. .IP \fIw\fP 1i
  510. Specifies the Paned widget.
  511. .LP
  512. This function returns the number of panes in the Paned widget.  This is
  513. \fBnot\fP the same as the number of children, since the grips are also
  514. children of the Paned widget.
  515.