| blob | ac782a3a700fba2daa488b641f6a91bc2148e927 |
1 .\" ***** BEGIN LICENSE BLOCK *****
2 .\" Version: MPL 1.1/GPL 2.0/LGPL 2.1
3 .\"
4 .\" The contents of this file are subject to the Mozilla Public License Version
5 .\" 1.1 (the "License"); you may not use this file except in compliance with
6 .\" the License. You may obtain a copy of the License at
7 .\" http://www.mozilla.org/MPL/
8 .\"
9 .\" Software distributed under the License is distributed on an "AS IS" basis,
10 .\" WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11 .\" for the specific language governing rights and limitations under the
12 .\" License.
13 .\"
14 .\" The Original Code is the Microline Widget Library, originally made available under the NPL by Neuron Data <http://www.neurondata.com>.
15 .\"
16 .\" The Initial Developer of the Original Code is
17 .\" Netscape Communications Corporation.
18 .\" Portions created by the Initial Developer are Copyright (C) 1998
19 .\" the Initial Developer. All Rights Reserved.
20 .\"
21 .\" Contributor(s):
22 .\"
23 .\" Alternatively, the contents of this file may be used under the terms of
24 .\" either the GNU General Public License Version 2 or later (the "GPL"), or
25 .\" the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
26 .\" in which case the provisions of the GPL or the LGPL are applicable instead
27 .\" of those above. If you wish to allow use of your version of this file only
28 .\" under the terms of either the GPL or the LGPL, and not to allow others to
29 .\" use your version of this file under the terms of the MPL, indicate your
30 .\" decision by deleting the provisions above and replace them with the notice
31 .\" and other provisions required by the GPL or the LGPL. If you do not delete
32 .\" the provisions above, a recipient may use your version of this file under
33 .\" the terms of any one of the MPL, the GPL or the LGPL.
34 .\"
35 .\" In addition, as a special exception to the GNU GPL, the copyright holders
36 .\" give permission to link the code of this program with the Motif and Open
37 .\" Motif libraries (or with modified versions of these that use the same
38 .\" license), and distribute linked combinations including the two. You
39 .\" must obey the GNU General Public License in all respects for all of
40 .\" the code used other than linking with Motif/Open Motif. If you modify
41 .\" this file, you may extend this exception to your version of the file,
42 .\" but you are not obligated to do so. If you do not wish to do so,
43 .\" delete this exception statement from your version.
44 .\"
45 .\" ***** END LICENSE BLOCK *****
46 .TH XmLGrid 3X "R1" "XML1" "XML"
47 .SH NAME
48 XmLGrid
49 .SH SYNOPSIS
50 #include <XmL/Grid.h>
51 .LP
52 .SH DESCRIPTION
53 A Grid consists of cells in rows and columns. There are two basic
54 cell types, defined by the nature of the cell content: STRING (XmString
55 format), and PIXMAP (pixmap images). STRING cells may allow editing.
56 Cells and regions within the Grid may be formatted with borders and
57 shadowing. Rows and columns may be fixed on the top, bottom,
58 left and right to remain in view while scrolling horizontally or
59 vertically. There may be heading and footer rows at the top and
60 bottom, and heading and footer columns at the left and right,
61 in addition to the content rows and columns in the center of
62 the Grid. While headings and footers must be fixed, content rows
63 may scroll or may also be fixed on the top, bottom, left and right.
64 .SS Class Information
65 Grid inherits from XmManager, Constraint, Composite and Core. Its
66 class pointer is xmlGridWidgetClass. Its class name is XmLGrid.
67 .SS New Resources
68 The Grid resources defined below affect its overall behavior, layout and
69 appearance. Definitions of resources affecting rows, columns and
70 cells follow the Grid resource definitions.
72 .nf
73 .ft B
74 Name Class
75 Type Default Access
76 .ft P
77 XmNallowColumnHide XmCAllowColumnHide
78 Boolean False CSG
79 XmNallowColumnResize XmCAllowColumnResize
80 Boolean False CSG
81 XmNallowDragSelected XmCAllowDragSelected
82 Boolean False CSG
83 XmNallowDrop XmCAllowDrop
84 Boolean False CSG
85 XmNallowRowHide XmCAllowRowHide
86 Boolean False CSG
87 XmNallowRowResize XmCAllowRowResize
88 Boolean False CSG
89 XmNautoSelect XmCAutoSelect
90 Boolean True CSG
91 XmNblankBackground XmCBlankBackground
92 Pixel Dynamic CSG
93 XmNbottomFixedCount XmCBottomFixedCount
94 int 0 CSG
95 XmNbottomFixedMargin XmCBottomFixedMargin
96 Dimension 0 CSG
97 XmNcolumns XmCColumns
98 int 0 CSG
99 XmNdebugLevel XmCDebugLevel
100 int 0 CSG
101 XmNeditTranslations XmCTranslations
102 XtTranslations Dynamic CSG
103 XmNfontList XmCFontList
104 XmFontList Dynamic CSG
105 XmNfooterColumns XmCFooterColumns
106 int 0 CSG
107 XmNfooterRows XmCFooterRows
108 int 0 CSG
109 XmNglobalPixmapHeight XmCGlobalPixmapHeight
110 Dimension 0 CSG
111 XmNglobalPixmapWidth XmCGlobalPixmapWidth
112 Dimension 0 CSG
113 XmNheadingColumns XmCHeadingColumns
114 int 0 CSG
115 XmNheadingRows XmCHeadingRows
116 int 0 CSG
117 XmNhiddenColumns XmCHiddenColumns
118 int 0 G
119 XmNhiddenRows XmCHiddenRows
120 int 0 G
121 XmNhighlightRowMode XmCHighlightRowMode
122 Boolean False CSG
123 XmNhighlightThickness XmCHighlightThickness
124 Dimension 2 CSG
125 XmNhorizontalScrollBar XmCHorizontalScrollBar
126 Widget Dynamic G
127 XmNhorizontalSizePolicy XmCHorizontalSizePolicy
128 unsigned char XmCONSTANT CSG
129 XmNhsbDisplayPolicy XmCHsbDisplayPolicy
130 unsigned char XmAS_NEEDED CSG
131 XmNimmediateDraw XmCImmediateDraw
132 Boolean False CSG
133 XmNlayoutFrozen XmCLayoutFrozen
134 Boolean False CSG
135 XmNleftFixedCount XmCLeftFixedCount
136 int 0 CSG
137 XmNleftFixedMargin XmCLeftFixedMargin
138 Dimension 0 CSG
139 XmNrightFixedCount XmCRightFixedCount
140 int 0 CSG
141 XmNrightFixedMargin XmCRightFixedMargin
142 Dimension 0 CSG
143 XmNrows XmCRows
144 int 0 CSG
145 XmNscrollBarMargin XmCScrollBarMargin
146 Dimension 2 CSG
147 XmNscrollColumn XmCScrollColumn
148 int Dynamic CSG
149 XmNscrollRow XmCScrollRow
150 int Dynamic CSG
151 XmNselectBackground XmCSelectBackground
152 Pixel Dynamic CSG
153 XmNselectForeground XmCSelectForeground
154 Pixel Dynamic CSG
155 XmNselectionPolicy XmCGridSelectionPolicy
156 unsigned char XmSELECT_BROWSE_ROW CSG
157 XmNshadowRegions XmCShadowRegions
158 int 511 CSG
159 XmNshadowType XmCShadowType
160 unsigned char XmSHADOW_IN CSG
161 XmNsimpleHeadings XmCSimpleHeadings
162 String NULL CSG
163 XmNsimpleWidths XmCSimpleWidths
164 String NULL CSG
165 XmNtextWidget XmCTextWidget
166 Widget Dynamic G
167 XmNtopFixedCount XmCTopFixedCount
168 int 0 CSG
169 XmNtopFixedMargin XmCTopFixedMargin
170 Dimension 0 CSG
171 XmNtraverseTranslations XmCTranslations
172 XtTranslations Dynamic CSG
173 XmNuseAverageFontWidth XmCUseAverageFontWidth
174 Boolean True CSG
175 XmNverticalScrollBar XmCVerticalScrollBar
176 Widget 0 G
177 XmNverticalSizePolicy XmCVerticalSizePolicy
178 unsigned char XmCONSTANT CSG
179 XmNvisibleColumns XmCVisibleColumns
180 int 0 CSG
181 XmNvisibleRows XmCVisibleRows
182 int 0 CSG
183 XmNvsbDisplayPolicy XmCVsbDisplayPolicy
184 unsigned char XmAS_NEEDED CSG
185 .fi
186 .IP XmNallowColumnHide
187 This resource only has effect when XmNallowColumnResize is True.
188 If the user is able to resize columns, this resource controls
189 whether a user can hide a column by resizing it to a zero width.
190 If True, a user may size columns to a zero width (hiding them) and
191 if False (the default), a user will not be able to resize a column
192 to a zero width.
193 .IP XmNallowColumnResize
194 If True, the user may resize a column by dragging the right
195 edge of a cell in a heading row. When the user resizes a column,
196 the column's XmNcolumnSizePolicy is set to XmCONSTANT and the
197 column's XmNcolumnWidth is set to the pixel width chosen by the
198 user. If the Grid contains no heading rows, this resource has no
199 effect. If False, interactive column resizing is disabled.
200 .IP XmNallowDragSelected
201 If True, the user may interactively drag cell contents (strings)
202 to a drop site. If False, dragging is disabled.
203 .IP XmNallowDrop
204 If True, the user is allow to drop cell contents (strings) into the
205 Grid. If False, the Grid will not register itself as a drop site.
206 .IP XmNallowRowHide
207 This resource only has effect when XmNallowRowResize is True.
208 If the user is able to resize rows, this resource controls
209 whether a user can hide a row by resizing it to a zero height.
210 If True, a user may size rows to a zero height (hiding them) and
211 if False (the default), a user will not be able to resize a row
212 to a zero height.
213 .IP XmNallowRowResize
214 If True, the user may resize a row by dragging the bottom edge of
215 a cell in a heading column. When the user resizes a row, the
216 row's XmNrowSizePolicy is set to XmCONSTANT and the row's
217 XmNrowHeight is set to the pixel height chosen by the user. If
218 the Grid contains no heading columns, this resource has no effect.
219 If False, interactive row resizing is disabled.
220 .IP XmNautoSelect
221 If set to True (the default) and the Grid's XmNselectionPolicy is
222 XmSELECT_BROWSE_ROW, the Grid will select its first row when it
223 is realized. No callback is generated by this action. If False,
224 no initial row will be selected.
225 .IP XmNblankBackground
226 If a Grid has a horizontal scrollbar which is scrolled completely
227 to the right or a vertical scrollbar which is scrolled to the
228 bottom, an empty area can exist after the last set of scrolling cells. The
229 color of this empty region is set by the XmNblankBackground
230 resource. It will only be visible when the Grid is scrolled fully
231 to the right or bottom. This value is initially set to the background
232 color of the Grid widget.
233 .IP XmNbottomFixedCount
234 The number of fixed rows at the bottom of the Grid including
235 footer rows. Since footer rows must be fixed, this value may not
236 be set smaller than the number of footer rows. If this value is
237 greater than the total number of rows, then as additional rows
238 are added they will be fixed until this value is reached.
239 .IP XmNbottomFixedMargin
240 The height, in pixels, of the margin between the bottom fixed
241 rows and any rows above them.
242 .IP XmNcolumns
243 The number of content columns. Setting this value will add content
244 columns to the Grid if the value set is greater than the current number
245 of content columns. Likewise, setting this value to a number less
246 than the current number of content columns will cause content columns
247 to be deleted. The Grid updates this resource to reflect the
248 current number of content columns every time a content column is
249 added or removed. To get the total number of columns in the
250 Grid (heading, content and footer) add this value to the number
251 of heading and footer columns.
252 .IP XmNdebugLevel
253 If set to a value greater than 0, debugging messages will be
254 printed to stderr. When set to 0 (the default) only error
255 messages will be reported.
256 .IP XmNeditTranslations
257 The translations merged into the Text widget child of the Grid
258 when the Grid goes from traverse mode into edit mode.
259 .IP XmNfontList
260 The default font list for new cells. Changing this resource
261 does not affect existing cells. If this value is NULL, a
262 font list is obtained from the nearest parent that is a
263 subclass of BulletinBoard, MenuShell, or VendorShell.
264 .IP XmNfooterColumns
265 The number of footer columns. Setting this value will add footer
266 columns to the Grid if the value set is greater than the current number
267 of footer columns. Likewise, setting this value to a number less
268 than the current number of footer columns will cause footer columns
269 to be deleted. The Grid updates this resource to reflect the
270 current number of footer columns every time a footer column is
271 added or removed.
272 .IP XmNfooterRows
273 The number of footer rows. Setting this value will add footer rows
274 to the Grid if the value set is greater than the current number
275 of footer rows. Likewise, setting this value to a number less
276 than the current number of footer rows will cause footer rows
277 to be deleted. The Grid updates this resource to reflect the
278 current number of footer rows every time a footer row is
279 added or removed.
280 .IP XmNglobalPixmapHeight
281 If non-zero, this value specifies the height of every pixmap
282 contained in the cells of the Grid. You should set this
283 resource only if all cell pixmaps have equal size.
284 If you set this resource, you should also set
285 XmNglobalPixmapWidth to the width of the pixmaps.
286 Setting this value will increase performance when setting
287 cell pixmaps since if this value is not set, the Grid will
288 need to perform a query to determine the dimensions of any
289 pixmap set. You should leave this value at 0 (the default)
290 if you have pixmaps of varying size in the Grid.
291 .IP XmNglobalPixmapWidth
292 This resource should be used with XmNglobalPixmapHeight. See
293 XmNglobalPixmapHeight for details.
294 .IP XmNheadingColumns
295 The number of heading columns. Setting this value will add heading
296 columns to the Grid if the value set is greater than the current number
297 of heading columns. Likewise, setting this value to a number less
298 than the current number of heading columns will cause heading columns
299 to be deleted. The Grid updates this resource to reflect the
300 current number of heading columns every time a heading column is
301 added or removed.
302 .IP XmNheadingRows
303 The number of heading rows. Setting this value will add heading rows
304 to the Grid if the value set is greater than the current number
305 of heading rows. Likewise, setting this value to a number less
306 than the current number of heading rows will cause heading rows
307 to be deleted. The Grid updates this resource to reflect the
308 current number of heading rows every time a heading row is
309 added or removed.
310 .IP XmNhiddenColumns
311 The total number of hidden columns. The Grid updates this
312 resource every time a column is hidden or unhidden. Hidden
313 columns are columns with a width of 0.
314 .IP XmNhiddenRows
315 The total number of hidden rows. The Grid updates this resource
316 every time a row is hidden or unhidden. Hidden rows are rows
317 with a height of 0.
318 .IP XmNhighlightRowMode
319 If True, a highlight is drawn around the entire row
320 containing the cell which has focus instead of just
321 around the current cell which has focus. If False (the default),
322 when a cell has focus, the highlight will be drawn only
323 around that cell.
324 .IP XmNhighlightThickness
325 The thickness of the highlight rectangle drawn in cells with focus.
326 This value must be 0 or 2.
327 .IP XmNhorizontalScrollBar
328 The widget ID of the Grid's horizontal ScrollBar.
329 .IP XmNhorizontalSizePolicy
330 Determines how the Grid sizes itself horizontally. Possible values:
332 .nf
333 XmVARIABLE /* Grid always requests full
334 width */
335 XmCONSTANT /* user or parent sets Grid
336 width and scrollbar is
337 displayed if required */
338 .fi
340 If this value is XmVARIABLE, the Grid determines the amount of
341 horizontal space required to display the entire Grid and
342 requests this space from its parent. When the width of the Grid
343 changes, it will request more or less space causing it to
344 shrink or expand as its parent widget allows. It will appear
345 truncated, without a horizontal ScrollBar, if not enough
346 space is given by the parent. If this value is XmCONSTANT the
347 user or the parent widget must define the Grid’s width and a
348 horizontal ScrollBar will appear if needed.
349 .IP XmNhsbDisplayPolicy
350 When XmNhorizontalSizePolicy is XmCONSTANT, this resource
351 controls whether to display the horizontal scroll bar if
352 all rows fit in the viewing area. Possible values:
354 .nf
355 XmSTATIC /* scrollbar always displays */
356 XmAS_NEEDED /* scrolbar only displayed when
357 scrolling is possible */
358 .fi
359 .IP XmNimmediateDraw
360 If False (the default), the Grid queues up and compresses
361 drawing events. For example, if you change a cell's background
362 and later change the cell's foreground, the Grid will only
363 draw the cell once to reflect the changes. This drawing
364 compression includes sending expose events to the X Server.
365 If you do not want the Grid to queue and compress drawing events,
366 you should set this value to True. You would want to set
367 this resource to True in the case where you had a very slow
368 connection to an X Server (over a serial line for instance).
369 If set to True and the line to the X Server is slow, more
370 drawing will be performed but the the drawing will show up faster.
371 .IP XmNlayoutFrozen
372 If True, the Grid's layout is frozen and the Grid will not
373 recompute its layout until this resource is set to False. When
374 this resource is set back to False, the layout will be recomputed
375 and the entire Grid will redraw. When rows or columns are added
376 to or deleted from the Grid, or if row heights, column widths or
377 margins are changed, the Grid must recompute its layout by determining which
378 cells to display on the screen. If a number of changes to the
379 Grid layout are going to take place, then by setting this resource
380 to True before executing the first change and setting it to False after
381 the last change is requested, the Grid will not recompute its
382 layout after each change. Setting this value will not affect what
383 is displayed on the screen as it is only used to increase performance. If
384 only a single layout change is requested, such as when adding or
385 deleting a single range of rows or columns, this resource should
386 not be used in an attempt to increase performance as the change
387 may not require a redraw of the Grid. This resource should also
388 not be used around code which does not cause the Grid to recompute
389 its layout, such as changing cell or border colors, as that
390 would decrease performance.
391 .IP XmNleftFixedCount
392 The number of fixed columns at the left of the Grid including
393 heading columns. Since heading columns must be fixed, this
394 value may not be set smaller than the number of heading columns. If
395 this value is greater than the total number of columns, then
396 as additional columns are added they will be fixed until this
397 value is reached.
398 .IP XmNleftFixedMargin
399 The width, in pixels, of the margin between the left fixed
400 columns and any columns to their right.
401 .IP XmNrightFixedCount
402 The number of fixed columns at the right of the Grid including
403 footer columns. Since footer columns must be fixed, this value
404 may not be set smaller than the number of footer columns. If
405 this value is greater than the total number of columns, then
406 as additional columns are added they will be fixed until this
407 value is reached.
408 .IP XmNrightFixedMargin
409 The width, in pixels, of the margin between the right fixed
410 columns and any columns to their left.
411 .IP XmNrows
412 The number of content rows. Setting this value will add content
413 rows to the Grid if the value set is greater than the current number
414 of content rows. Likewise, setting this value to a number less
415 than the current number of content rows will cause content rows
416 to be deleted. The Grid updates this resource to reflect the
417 current number of content rows every time a content row is
418 added or removed. To get the total number of rows in the
419 Grid (heading, content and footer) add this value to the number
420 of heading and footer rows.
421 .IP XmNscrollBarMargin
422 The margin, in pixels, between the ScrollBars and the displayed cells.
423 .IP XmNscrollColumn
424 The left-most scrolling content column currently displayed.
425 This value may be set to change the current scroll position.
426 If setting this value causes the scroll position to change, the Grid's scroll
427 callbacks will be called. If this value is set greater than the
428 last possible scrolling column, the Grid will scroll to the last
429 possible scrolling column. If this value is set less than the first possible
430 scrolling column, the Grid will scroll to the first possible scrolling column.
431 .IP XmNscrollRow
432 The top scrolling content row currently displayed. This value
433 may be set to change the current scroll position. If setting this
434 value causes the scroll position to change, the Grid's scroll
435 callbacks will be called. If this value is set greater than the
436 last possible scrolling row, the Grid will scroll to the last
437 possible scrolling row. If this value is set less than the first possible
438 scrolling row, the Grid will scroll to the first possible scrolling row.
439 .IP XmNselectBackground
440 The background color of cells, rows or columns which are
441 currently selected. This value is initially set to the foreground
442 color of the Grid widget.
443 .IP XmNselectForeground
444 The foreground color of cells, rows or columns which are
445 currently selected. This value is initially set to the background
446 color of the Grid widget.
447 .IP XmNselectionPolicy
448 Determines the types of selections allowed in the Grid.
449 In SELECT_NONE mode, user selections have no effect by default and
450 cell select callbacks are called each time a user selects a cell. The
451 application may set selections of rows/columns or cells. In
452 SELECT_SINGLE_ROW mode, one or zero content rows may be selected.
453 In SELECT_BROWSE_ROW mode, one content row must be selected at all
454 times. In SELECT_MULTIPLE_ROW, multiple content rows
455 may be selected. In any of the SELECT_..._ROW modes, when cells
456 in heading or footer rows are selected by a user, the Grid will
457 call its cell select callbacks. Therefore, the application must
458 be sure to check the type of selection made in its select
459 callback(s). In SELECT_CELL mode, arbitrary regions of cells
460 in content rows and content columns may be selected. A user
461 may select cells in heading rows to select columns and cells
462 in heading columns to select rows. Possible values:
464 .nf
465 XmSELECT_NONE /* no selections */
466 XmSELECT_SINGLE_ROW /* 0 or 1 row selection */
467 XmSELECT_BROWSE_ROW /* 1 row selection */
468 XmSELECT_MULTIPLE_ROW /* multiple row selection */
469 XmSELECT_CELL /* multiple row, column,
470 cell selections */
471 .fi
473 .IP XmNshadowRegions
474 Determines which regions are drawn with shadows. There are 9 regions
475 in the Grid numbered as follows:
477 .nf
478 1 2 4
479 8 16 32
480 64 128 256
481 .fi
483 Where 1, 2 and 4 combine to make the top fixed rows. 1, 8 and 64
484 combine into the left fixed columns, 16 is the scrolling region,
485 etc. The value should be set to the summation of the region’s
486 numbers which should be drawn with a shadow. For example, if
487 this value is set to 428 (64 + 128 + 256) the Grid will draw
488 a shadow box around each region in the bottom row. Regions not
489 included are drawn without shadows.
490 .IP XmNshadowType
491 The type of shadows to draw around the regions of the Grid.
492 Possible values:
494 .nf
495 XmSHADOW_ETCHED_IN /* etched in appearance */
496 XmSHADOW_ETCHED_OUT /* etched out appearance */
497 XmSHADOW_IN /* inset appearance */
498 XmSHADOW_OUT /* outset appearance */
499 .fi
500 .IP XmNsimpleHeadings
501 This resource may be used to set cell strings in the first
502 heading row in a Grid with a simple C string. The value passed
503 should be a null-terminated C string containing headings
504 separated by the pipe symbol. A heading row must exist at
505 the time of this call which contains the number of cells
506 which will be affected or the Grid will generate a warning.
507 The following example sets the headings of a Grid to "First",
508 "Second" and "Third":
510 .nf
511 XtVaSetValues(grid,
512 XmNsimpleHeadings, "First|Second|Third",
513 NULL);
514 .fi
516 The Grid makes a copy of the string passed to it for this resource
517 in a SetValues call. The Grid will return a pointer to this
518 internal copy of the string if GetValues is called for this resource
519 and the pointer returned should not be freed by an application.
520 .IP XmNsimpleWidths
521 This resource may be used to set the widths of columns in a Grid.
522 The value passed should be a null-terminated C string containing
523 numbers specifying widths and a letter 'p' or 'c' following the
524 number to indicate whether the width is in pixels or characters.
525 A space should be used after each letter to separate columns.
526 The columns affected by the call must exist at the time
527 a value is set, or the Grid will generate a warning. The
528 following example sets the width of the first column
529 to 10 characters wide and the second column to 20 pixels wide:
531 .nf
532 XtVaSetValues(grid,
533 XmNsimpleWidths, "10c 20p",
534 NULL);
535 .fi
537 The Grid makes a copy of the string passed to it for this resource
538 in a SetValues call. The Grid will return a pointer to this
539 internal copy of the string if GetValues is called for this resource
540 and the pointer returned should not be freed by an application.
541 .IP XmNtextWidget
542 The widget ID of the Grid's Text widget.
543 .IP XmNtopFixedCount
544 The number of fixed rows at the top of the Grid including
545 heading rows. Since heading rows must be fixed, this value may
546 not be set smaller than the number of heading rows. If this value is
547 greater than the total number of rows, then as additional rows
548 are added they will be fixed until this value is reached.
549 .IP XmNtopFixedMargin
550 The height, in pixels, of the margin between the top fixed rows
551 and any rows below them.
552 .IP XmNtraverseTranslations
553 The translations merged into the Text widget child of the Grid
554 when the Grid goes from edit mode into traverse mode.
555 .IP XmNuseAverageFontWidth
556 Cells in the Grid which contain text calculate their preferred
557 width based on the font list character width of the font list
558 assigned to the cell. The Grid calculates the font list character
559 width when font lists are assigned to cells. If the value of
560 this resource is True, the font list character width will be
561 calculated by averaging all of the glyph widths in the font list. If this
562 value is False, the font list character width will equal the
563 the maximum glyph width in the font list. Changing this resource
564 only affects font lists assigned after this value is changed, it does not
565 affect the current layout of the Grid. Also, this resource
566 only affects cells containing proportional fonts since a fixed
567 width font's average glyph width will equal its maximum glyph width.
568 .IP XmNverticalScrollBar
569 The widget ID of the Grid's vertical ScrollBar.
570 .IP XmNverticalSizePolicy
571 Determines how the Grid sizes itself vertically. Possible values:
573 .nf
574 XmVARIABLE /* Grid always requests
575 full height */
576 XmCONSTANT /* user or parent sets Grid
577 height and scrollbar is
578 displayed if needed */
579 .fi
581 If this value is XmVARIABLE, the Grid determines the amount
582 of vertical space required to display the entire Grid and
583 requests this space from its parent. When the height of the Grid
584 changes, it will request more or less space causing it to
585 shrink or expand as its parent widget allows. It will appear
586 truncated, without a vertical ScrollBar, if not enough space
587 is given by the parent. If this value is XmCONSTANT the user or
588 the parent widget must define the Grids height and a vertical
589 ScrollBar will appear if needed.
590 .IP XmNvisibleColumns
591 Setting this resource causes the Grid to request a width from
592 its parent equal to the value set multiplied by the width of
593 a standard 8 character wide cell. The actual width in pixels
594 requested is:
596 .nf
597 shadowThickness * 2 + value * (4 + 8 * defaultFontWidth +
598 defaultLeftMargin + defaultRightMargin)
599 .fi
601 The width requested is not determined using any existing column
602 values. For example, if you have 3 columns which are each 20
603 characters wide and you set XmNvisibleColumns to 3, the width
604 requested will not fit the 3 columns of 20 characters, it will
605 fit 3 columns of 8 characters (without Grid borders). The width
606 requested does depend on the default font in the Grid, however,
607 to determine the width of a standard 8 character wide cell.
608 If you want the Grid to request a width equal to the width of
609 the existing columns, see the XmNhorizontalSizePolicy resource's
610 XmVARIABLE setting.
611 .IP XmNvisibleRows
612 Setting this resource causes the Grid to request a height from
613 its parent equal to the value set multiplied by the height
614 of a default 1 character height cell. The actual height in pixels
615 requested is:
617 .nf
618 shadowThickness * 2 + value * (4 + defaultFontHeight +
619 defaultTopMargin + defaultBottomMargin)
620 .fi
622 The height requested is not determined using any existing row
623 values. For example, if you have 10 rows which are each 3
624 characters high and you set XmNvisibleRows to 10, the height
625 requested will not fit the 10 existing rows, it will fit
626 fit 10 rows of 1 character height (without Grid borders).
627 The height requested does depend on the default font in the
628 Grid, however, to determine the height of a standard cell.
629 If you want the Grid to request a height equal to the height of
630 the existing rows, see the XmNverticalSizePolicy resource's
631 XmVARIABLE setting.
632 .IP XmNvsbDisplayPolicy
633 When XmNverticalSizePolicy is XmCONSTANT, this resource
634 controls whether to display the vertical scroll bar if
635 all rows fit in the viewing area. Possible values:
637 .nf
638 XmSTATIC /* scrollbar always displays */
639 XmAS_NEEDED /* scrolbar only displayed when
640 scrolling is possible */
641 .fi
642 .SS Row/Column/Cell Resources
643 Grid defines the resources in the table below affecting rows,
644 columns and cells. A SetValues call can set values for a
645 single column using XmNcolumn or for a range of columns using
646 XmNcolumnRangeStart and XmNcolumnRangeEnd. Row values can be
647 set using XmNrow or XmNrowRangeStart and XmNrowRangeEnd.
648 Cell values can be set for a single cell using XmNcolumn and
649 XmNrow, or a range of cells using a variety of combinations
650 of row and column specifications. A GetValues call can retrieve
651 values for a column using XmNcolumnPtr, a row using XmNrowPtr,
652 and a cell using both XmNcolumnPtr and XmNrowPtr.
654 .nf
655 .ft B
656 Name Class
657 Type Default Access
658 .ft P
659 XmNcellAlignment XmCCellAlignment
660 unsigned char XmALIGNMENT_CENTER SG
661 XmNcellBackground XmCCellBackground
662 Pixel Dynamic SG
663 XmNcellBottomBorderColor XmCCellBottomBorderColor
664 Pixel Dynamic SG
665 XmNcellBottomBorderType XmCBottomBorderType
666 unsigned char XmBORDER_LINE SG
667 XmNcellColumnSpan XmCCellColumnSpan
668 int 0 SG
669 XmNcellDefaults XmCCellDefaults
670 Boolean False S
671 XmNcellEditable XmCCellEditable
672 Boolean False SG
673 XmNcellFontList XmCCellFontList
674 XmFontList Dynamic SG
675 XmNcellForeground XmCCellForeground
676 Pixel Dynamic SG
677 XmNcellLeftBorderColor XmCCellLeftBorderColor
678 Pixel Dynamic SG
679 XmNcellLeftBorderType XmCCellLeftBorderType
680 unsigned char XmBORDER_LINE SG
681 XmNcellMarginBottom XmCCellMarginBottom
682 Dimension 0 SG
683 XmNcellMarginLeft XmCCellMarginLeft
684 Dimension 0 SG
685 XmNcellMarginRight XmCCellMarginRight
686 Dimension 0 SG
687 XmNcellMarginTop XmCCellMarginTop
688 Dimension 0 SG
689 XmNcellPixmap XmCCellPixmap
690 Pixmap XmUNSPECIFIED_PIXMAP SG
691 XmNcellPixmapMask XmCCellPixmapMask
692 Pixmap XmUNSPECIFIED_PIXMAP SG
693 XmNcellRightBorderColor XmCCellRightBorderColor
694 Pixel Dynamic SG
695 XmNcellRightBorderType XmCCellRightBorderType
696 unsigned char XmBORDER_LINE SG
697 XmNcellRowSpan XmCCellRowSpan
698 int 0 SG
699 XmNcellString XmCXmString
700 XmString NULL SG
701 XmNcellTopBorderColor XmCCellTopBorderColor
702 Pixel Dynamic SG
703 XmNcellTopBorderType XmCCellTopBorderType
704 unsigned char XmBORDER_LINE SG
705 XmNcellType XmCCellType
706 unsigned char XmSTRING_CELL SG
707 XmNcellUserData XmCUserData
708 XtPointer 0 SG
709 XmNcolumn XmCGridColumn
710 int -1 S
711 XmNcolumnPtr (none)
712 XtPointer 0 G
713 XmNcolumnRangeEnd XmCColumnRangeEnd
714 int -1 S
715 XmNcolumnRangeStart XmCColumnRangeStart
716 int -1 S
717 XmNcolumnSizePolicy XmCColumnSizePolicy
718 unsigned char XmVARIABLE SG
719 XmNcolumnStep XmCColumnStep
720 int 1 S
721 XmNcolumnType XmCColumnType
722 unsigned char XmCONTENT S
723 XmNcolumnWidth XmCColumnWidth
724 Dimension 8 SG
725 XmNcolumnUserData XmCUserData
726 XtPointer 0 SG
727 XmNrow XmCGridRow
728 int -1 S
729 XmNrowHeight XmCRowHeight
730 Dimension 1 SG
731 XmNrowPtr (none)
732 XtPointer 0 G
733 XmNrowRangeEnd XmCRowRangeEnd
734 int -1 S
735 XmNrowRangeStart XmCRowRangeStart
736 int -1 S
737 XmNrowSizePolicy XmCRowSizePolicy
738 unsigned char XmVARIABLE SG
739 XmNrowStep XmCRowStep
740 int 1 S
741 XmNrowType XmCRowType
742 unsigned char XmCONTENT S
743 XmNrowUserData XmCUserData
744 XtPointer 0 SG
745 .fi
746 .IP XmNcellAlignment
747 Determines the alignment of the XmString or Pixmap contained in
748 the cell. Possible values:
750 .nf
751 XmALIGNMENT_LEFT /* left, centered vertically */
752 XmALIGNMENT_CENTER /* centered horizontally and
753 vertically */
754 XmALIGNMENT_RIGHT /* right, centered vertically */
755 XmALIGNMENT_TOP_LEFT /* top left */
756 XmALIGNMENT_TOP /* top, centered horizontally */
757 XmALIGNMENT_TOP_RIGHT /* top right */
758 XmALIGNMENT_BOTTOM_LEFT /* bottom left */
759 XmALIGNMENT_BOTTOM /* bottom, centered horizontally */
760 XmALIGNMENT_BOTTOM_RIGHT /* bottom right */
761 .fi
763 If a cell Pixmap does not have a width or height set, the
764 cell's alignment will be top left regardless of the value of
765 this resource since any other alignment could not be calculated.
766 .IP XmNcellBackground
767 The cell's background color.
768 .IP XmNcellBottomBorderColor
769 The color of the cell's bottom border. If the cell's bottom
770 border type is XmBORDER_NONE, no bottom border will be drawn and this
771 resource has no effect. The default value of this resource is the
772 bottom shadow color of the Grid.
773 .IP XmNcellBottomBorderType
774 Determines the type of border to draw at the bottom of
775 the cell. Possible values:
777 .nf
778 XmBORDER_NONE /* no border */
779 XmBORDER_DASH /* dashed line */
780 XmBORDER_LINE /* line border */
781 .fi
783 .IP XmNcellColumnSpan
784 The number of columns to the right that are spanned by this cell.
785 You may combine this with a row span to span both rows and columns.
786 When a cell spans into adjacent cells, those spanned cells are
787 not displayed; instead, the contents of the spanning cell are
788 displayed in the spanned area. This effectively makes the spanning
789 cell larger while not changing the cell's row or column size.
790 If cell spans overlap, the visual behavior of the spanned cells
791 will become undefined. If rows or columns are added or deleted
792 inside a spanned area, the visual behavior of the spanned
793 cells will become undefined. If rows or columns are moved or
794 reordered in a way which does not preserve existing cell spans,
795 the visual behavior of the spanned cells will become undefined. The
796 width of a column span in pixels cannnot exceed the maximum
797 value of the type Dimension. Setting a column span on a cell
798 sets its preferred cell width to 4 pixels. All cells in a span must
799 exist at the time the span is set.
800 .IP XmNcellDefaults
801 Setting this value to True in a SetValues call indicates that
802 the call is setting the default cell values. The default cell
803 values can be assigned on a per-column basis by setting this
804 resource to True and setting a column (using XmNcolumn) or a
805 range of columns in the SetValues call. For example, to set
806 the default editibility for cells in column 0 to editable,
807 you could:
809 .nf
810 XtVaSetValues(grid,
811 XmNcellDefaults, True,
812 XmNcolumn, 0,
813 XmNcellEditable, True,
814 NULL);
815 .fi
817 This specifies that any cell created (cells are created by adding
818 rows or columns) in column 0 will be editable by default. If you
819 do not specify a column in a SetValues call where XmNcellDefaults is
820 True, the default cell values in the call will be set for all columns.
821 Inotherwords, it will set the defaults for any new cell created.
822 This value is always reset to False after a SetValues call completes.
823 .IP XmNcellEditable
824 Allow (True) or disallow (False) a user either by typing,
825 using a cut/paste or drag/drop operation, to edit the
826 cell. This may only be set to True for cells with a XmNcellType
827 of XmSTRING_CELL.
828 .IP XmNcellFontList
829 The font list used for the cell's text. By default, the value
830 of this resource is set to the Grid's XmNfontList. Changing this
831 value may cause the row or column containing the cell to resize if
832 the row's XmNrowSizePolicy or the column's XmNcolumnSizePolicy
833 is XmVARIABLE.
834 .IP XmNcellForeground
835 The cell's foreground color.
836 .IP XmNcellLeftBorderColor
837 The color of the cell's left border. If the cell's left border
838 type is XmBORDER_NONE, no left border will be drawn and this resource
839 has no effect. The default value of this resource is the top shadow
840 color of the Grid.
841 .IP XmNcellLeftBorderType
842 Determines the type of border to draw at the left of the cell.
843 Possible values:
845 .nf
846 XmBORDER_NONE /* no border */
847 XmBORDER_DASH /* dashed line */
848 XmBORDER_LINE /* line border */
849 .fi
851 .IP XmNcellMarginBottom
852 The height, in pixels, of the margin between the bottom of
853 the cell and the cell's contents.
854 .IP XmNcellMarginLeft
855 The width, in pixels, of the margin between the left of
856 the cell and the cell's contents.
857 .IP XmNcellMarginRight
858 The width, in pixels, of the margin between the right of
859 the cell and the cell's contents.
860 .IP XmNcellMarginTop
861 The height, in pixels, of the margin between the top of
862 the cell and the cell's contents.
863 .IP XmNcellPixmap
864 The Pixmap to draw in the cell if the cell's type is XmPIXMAP_CELL.
865 As in other widgets, the Grid does not make a copy of the Pixmap.
866 Therefore, the Pixmap should not be freed until it is
867 no longer required to be displayed by the Grid. Changing this
868 value may cause the row or column containing the cell to resize
869 if the row's XmNrowSizePolicy or the column's XmNcolumnSizePolicy
870 is XmVARIABLE. This value may be XmUNSPECIFIED_PIXMAP.
871 .IP XmNcellPixmapMask
872 The pixmap mask to use when drawing a cell if the cell's type is
873 XmPIXMAP_CELL. This value must be either XmUNSPECIFIED_PIXMAP (the
874 default) or a Pixmap of depth 1. If set to a Pixmap of depth 1,
875 the Pixmap specified will be used as a mask for drawing the cell's
876 contents. As in other widgets, the Grid does not make a copy of
877 the Pixmap passed. Therefore, the Pixmap should not be freed until
878 it is no longer required to be used by the Grid.
879 .IP XmNcellRightBorderColor
880 The color of the cell's right border. If the cell's right border
881 type is XmBORDER_NONE, no right border will be drawn and this resource
882 has no effect. The default value of this resource is the bottom
883 shadow color of the Grid.
884 .IP XmNcellRightBorderType
885 Determines the type of border to draw at the right of the cell.
886 Possible values:
888 .nf
889 XmBORDER_NONE /* no border */
890 XmBORDER_DASH /* dashed line */
891 XmBORDER_LINE /* line border */
892 .fi
894 .IP XmNcellRowSpan
895 The number of rows below that are spanned by this cell. You may
896 combine this with a column span to span both rows and columns.
897 When a cell spans into adjacent cells, those spanned cells
898 are not displayed; instead, the contents of the spanning cell
899 are displayed in the spanned area. This effectively makes the
900 spanning cell larger while not changing the cell's row or column size.
901 If cell spans overlap, the visual behavior of the spanned cells
902 will become undefined. If rows or columns are added or deleted
903 inside a spanned area, the visual behavior of the spanned cells will
904 become undefined. If rows or columns are moved or reordered in
905 a way which does not preserve existing cell spans, the visual
906 behavior of the spanned cells will become undefined. The height
907 of a row span in pixels cannnot exceed the maximum value of the
908 type Dimension. Setting a row span on a cell sets its preferred
909 cell height to 4 pixels. All cells in a span must exist at the time
910 the span is set.
911 .IP XmNcellString
912 The compound string to draw in the cell if the cell's type
913 is XmSTRING_CELL. As in other widgets, the Grid
914 makes a copy of the string and so the string may be freed after
915 it is used to set this value. Retrieving this value will return
916 a copy of the cell's string, therefore the retrieved string should
917 be freed when it will no longer be used. This value
918 may be NULL.
919 .IP XmNcellTopBorderColor
920 The color of the cell's top border. If the cell's top border
921 type is XmBORDER_NONE, no top border will be drawn and this resource
922 has no effect. The default value of this resource is the top shadow color
923 of the Grid.
924 .IP XmNcellTopBorderType
925 Determines the type of border to draw at the top of the cell.
926 Possible values:
928 .nf
929 XmBORDER_NONE /* no border */
930 XmBORDER_DASH /* dashed line */
931 XmBORDER_LINE /* line border */
932 .fi
934 .IP XmNcellType
935 The type of the cell. Possible values:
937 .nf
938 XmSTRING_CELL /* cell displaying XmString */
939 XmPIXMAP_CELL /* cell displaying a Pixmap */
940 .fi
942 Changing this value may cause the row or column containing the
943 cell to resize if the row's XmNrowSizePolicy or the column's
944 XmNcolumnSizePolicy is XmVARIABLE. Changing a cell's type from
945 XmSTRING_CELL to XmPIXMAP_CELL will free the XmNcellString
946 currently contained in the cell and will set the XmNcellString
947 to NULL. Changing from XmPIXMAP_CELL to XmSTRING_CELL will
948 cause the cell's XmNcellPixmap to be set to XmUNSPECIFIED_PIXMAP.
949 .IP XmNcellUserData
950 A pointer value unused by the Grid. This resource allows you
951 to attach a pointer to any cell in the Grid.
952 .IP XmNcolumn
953 Defines which column(s) or cell(s) a SetValues call will affect.
954 A value of -1 (the default) means all columns. This value is
955 always reset to -1 after the SetValues call completes. The value of 0
956 defines the first column of a column type. This resource may not
957 be used in a GetValues call.
958 .IP XmNcolumnPtr
959 Defines which column, or column a cell is contained in, a
960 GetValues call should retrieve values for. This value is a
961 pointer to a column which should be obtained using XmLGridGetColumn().
962 This resource may not be used in a SetValues call.
963 .IP XmNcolumnRangeEnd
964 Defines the last column or column of cells in a range which a
965 SetValues call will affect. This resource may not be used in a
966 GetValues call. This resource must be used with the
967 XmNcolumnRangeStart resource.
968 .IP XmNcolumnRangeStart
969 Defines the first column or column of cells in a range which
970 a SetValues call will affect. This resource may not be used
971 in a GetValues call. This resource must be used with the
972 XmNcolumnRangeEnd resource.
973 .IP XmNcolumnSizePolicy
974 Defines how the column width is determined. Possible values:
976 .nf
977 XmCONSTANT /* column size is fixed */
978 XmVARIABLE /* column may resize when
979 cell size changes */
980 .fi
982 If XmVARIABLE, the column will size itself to the maximum
983 preferred width of the column's cells. For cells containing text,
984 this usually equals the cell's average or maximum font list glyph
985 width multiplied by the XmNcolumnWidth (plus space for borders, etc).
986 If XmCONSTANT, the XmNcolumnWidth value is assumed to be in
987 pixels and the column width will equal that value.
988 .IP XmNcolumnStep
989 Defines the column increment when setting values of multiple
990 columns or cells in a SetValues call. For example, a column
991 step of 2 will skip every other column. This value is 1 by default
992 and will reset to 1 after a SetValues call completes.
993 .IP XmNcolumnType
994 Defines which type of columns or cells a SetValues call will
995 affect. This resource may not be used in a GetValues call.
996 Possible values:
998 .nf
999 XmALL_TYPES /* all column types - heading, content
1000 and footer */
1001 XmCONTENT /* columns containing the Grid's
1002 contents */
1003 XmHEADING /* heading columns on the far left */
1004 XmFOOTER /* footer columns on the far right */
1005 .fi
1007 This resource is used along with XmNcolumn or XmNcolumnRangeStart and
1008 XmNcolumnRangeEnd and determines which type of column the column or
1009 column range specifies. By default, this value is set to XmCONTENT.
1010 This value is always reset to XmCONTENT after a SetValues call completes.
1011 .IP XmNcolumnUserData
1012 A pointer value unused by the Grid. This resource allows you
1013 to attach a pointer to any column in the Grid.
1014 .IP XmNcolumnWidth
1015 If XmNcolumnSizePolicy is XmVARIABLE, the value of this resource
1016 represents the column width in characters and if a font list in
1017 any cell in the column is changed, the column will resize
1018 if required. The pixel width of a column is determined by the
1019 maximum preferred width of the column's cells. Cells containing
1020 text usually determine their preferred width by multiplying the
1021 cell's average or maximum font list glyph width by the column's
1022 XmNcolumnWidth. Pixmap cells ignore this resource since their
1023 preferred width is the width of their pixmap. If
1024 XmNcolumnSizePolicy is XmCONSTANT, the value of this resource
1025 represents the column width in pixels.
1026 .IP XmNrow
1027 Defines which row(s) or cell(s) a SetValues call will affect.
1028 A value of -1 (the default) means all rows. The value of 0
1029 defines the first row of a row type. This value is always
1030 reset to -1 after a SetValues call completes. This resource
1031 may not be used in a GetValues call.
1032 .IP XmNrowHeight
1033 If XmNrowSizePolicy is XmVARIABLE, the value of this resource
1034 represents the row height in characters and if a font list in
1035 any cell in this row is changed, the row will resize if required. The
1036 pixel height of a row is determined by the maximum preferred
1037 height of the row's cells. Cells containing text usually determine
1038 their preferred height by taking their maximum font list
1039 character height and multiplying it by the row's XmNrowHeight.
1040 Pixmap cells ignore this resource since their preferred height
1041 is the height of their pixmap. If XmNrowSizePolicy is
1042 XmCONSTANT, the value of this resource represents the row height in pixels.
1043 .IP XmNrowPtr
1044 Defines which row, or row a cell is contained in, a GetValues
1045 call should retrieve values for. This value is a pointer to a
1046 row which should be obtained using XmLGridGetRow(). This
1047 resource may not be used in a SetValues call.
1048 .IP XmNrowRangeEnd
1049 Defines the last row or row of cells in a range which a SetValues
1050 call will affect. This resource may not be used in a GetValues
1051 call. This resource must be used with the XmNrowRangeStart resource.
1052 .IP XmNrowRangeStart
1053 Defines the first row or row of cells in a range which a SetValues
1054 call will affect. This resource may not be used in a GetValues call.
1055 This resource must be used with the XmNrowRangeEnd resource.
1056 .IP XmNrowSizePolicy
1057 Defines how the row height is determined. Possible values:
1059 .nf
1060 XmCONSTANT /* row size is fixed */
1061 XmVARIABLE /* row may resize when cell
1062 size changes */
1063 .fi
1065 If XmVARIABLE, the row will size itself to the maximum preferred
1066 height of the row's cells. For cells containing text, this usually
1067 equals the cell's maximum font list glyph height multiplied
1068 by the XmNrowHeight (plus space for borders, etc). If XmCONSTANT,
1069 the XmNrowHeight value is assumed to be in pixels and the row
1070 height will equal that value.
1071 .IP XmNrowStep
1072 Defines the row increment when setting values of multiple rows
1073 or cells in a SetValues call. For example, a row step of 2 will
1074 skip every other row. This value is 1 by default and will reset to 1
1075 when a SetValue call completes.
1076 .IP XmNrowType
1077 Defines which type of rows or cells a SetValues call will affect.
1078 This resource may not be used in a GetValues call. Possible values:
1080 .nf
1081 XmALL_TYPES /* all row types - heading/content
1082 and footer */
1083 XmCONTENT /* rows containing the Grid's contents */
1084 XmHEADING /* heading rows on the top */
1085 XmFOOTER /* footer rows on the bottom */
1086 .fi
1088 This resource is used along with XmNrow or XmNrowRangeStart and
1089 XmNrowRangeEnd and determines which type of row the row or row
1090 range specifies. By default, this value is set to XmCONTENT.
1091 This value is always reset to XmCONTENT after a SetValues call completes.
1092 .IP XmNrowUserData
1093 A pointer value unused by the Grid. This resource allows you
1094 to attach a pointer to any row in the Grid.
1095 .SS Callback Resources
1096 Grid defines the following callback resources.
1098 .nf
1099 .ft B
1100 Callback Reasons Called When
1101 .ft P
1102 XmNactivateCallback XmCR_ACTIVATE Cell is activated with
1103 Return or double-click
1104 XmNaddCallback XmCR_ADD_CELL Row, column or cell is
1105 XmCR_ADD_COLUMN created by calling a function
1106 XmCR_ADD_ROW which adds rows or columns
1107 XmNcellDrawCallback XmCR_CELL_DRAW Cell is drawn
1108 XmNcellDropCallback XmCR_CELL_DROP Cell value was changed by new
1109 value dropped into cell
1110 XmNcellFocusCallback XmCR_CELL_FOCUS_IN Focus cell is set or changed
1111 XmCR_CELL_FOCUS_OUT
1112 XmNcellPasteCallback XmCR_CELL_PASTE Cell value was changed by new
1113 value pasted into cell
1114 XmNdeleteCallback XmCR_DELETE_CELL Row, column or cell is
1115 XmCR_DELETE_COLUMN deleted by calling a
1116 XmCR_DELETE_ROW function which deletes
1117 rows or columns
1118 XmNdeselectCallback XmCR_DESELECT_CELL Row, column or cell
1119 XmCR_DESELECT_COLUMN changes from selected
1120 XmCR_DESELECT_ROW to deselected (see also
1121 XmNselectionPolicy resource)
1122 XmNeditCallback XmCR_EDIT_BEGIN Cell edit begins, cancels,
1123 XmCR_EDIT_CANCEL completes or when an
1124 XmCR_EDIT_COMPLETE insert-begin occurs in
1125 XmCR_EDIT_INSERT a cell
1126 XmNresizeCallback XmCR_RESIZE_ROW Row or column is resized
1127 XmCR_RESIZE_COLUMN interactively
1128 XmNscrollCallback XmCR_SCROLL_ROW Current scrolled row or
1129 XmCR_SCROLL_COLUMN column position changes
1130 XmNselectCallback XmCR_SELECT_CELL Row, column or cell is
1131 XmCR_SELECT_COLUMN selected (see also
1132 XmCR_SELECT_ROW XmNselectionPolicy resource)
1133 .fi
1134 .SS Callback Structure
1135 Each callback function is passed a pointer to the structure
1136 shown below; however, only those values which are meaningful
1137 for the callback are set.
1139 .nf
1140 typedef struct
1141 {
1142 int reason; /* callback reason */
1143 XEvent *event; /* event causing callback or NULL */
1144 unsigned char rowType, columnType; /* row and column types */
1145 int row, int column; /* row and column positions */
1146 XRectangle *clipRect; /* clipping rectangle */
1147 XmLGridDrawInfoStruct *drawInfo; /* pointer to draw info */
1148 void *object; /* reserved */
1149 } XmLGridCallbackStruct;
1150 .fi
1152 The drawInfo pointer is set to point to the structure below for
1153 XmNcellDraw callbacks.
1155 .nf
1156 typedef struct
1157 {
1158 GC gc; /* GC used for drawing */
1159 XRectangle *cellRect; /* location/dimensions of
1160 cell (unclipped) */
1161 Dimension topMargin; /* cell margins */
1162 Dimension bottomMargin;
1163 Dimension leftMargin;
1164 Dimension rightMargin;
1165 Pixel foreground; /* cell foreground */
1166 Pixel background; /* cell background */
1167 Pixel selectForeground; /* cell foreground if selected */
1168 Pixel selectBackground; /* cell background if selected */
1169 XmFontList fontList; /* cell fontlist */
1170 unsigned char alignment; /* cell alignment */
1171 Boolean drawSelected; /* True if cell, row or
1172 column selected */
1173 int drawFocusType;
1174 /* type of focus cell has, one of:
1175 XmDRAW_FOCUS_NONE - cell does not have focus
1176 XmDRAW_FOCUS_CELL - focus is in cell
1177 XmDRAW_FOCUS_LEFT - cell is leftmost in focus row
1178 XmDRAW_FOCUS_RIGHT - cell is rightmost in focus row
1179 XmDRAW_FOCUS_MID - cell is in middle of focus row */
1181 XmStringDirection stringDirection;
1182 /* direction for string drawing */
1183 } XmLGridDrawInfoStruct;
1184 .fi
1186 The following table shows which values are set for which callback
1187 reasons. Elements not set will have undefined values.
1189 .nf
1190 .ft B
1191 Reason Values Set
1192 .ft P
1193 XmCR_ACTIVATE event, rowType, columnType, row, column
1194 XmCR_ADD_CELL rowType, columnType
1195 XmCR_ADD_COLUMN columnType
1196 XmCR_ADD_ROW rowType
1197 XmCR_CELL_DRAW event, rowType, columnType, row, column,
1198 clipRect, drawInfo
1199 XmCR_CELL_DROP rowType, columnType, row, column
1200 XmCR_CELL_FOCUS_IN rowType, columnType, row, column
1201 XmCR_CELL_FOCUS_OUT rowType, columnType, row, column
1202 XmCR_CELL_PASTE rowType, columnType, row, column
1203 XmCR_DELETE_CELL rowType, columnType
1204 XmCR_DELETE_COLUMN columnType
1205 XmCR_DELETE_ROW rowType
1206 XmCR_DESELECT_CELL event, rowType, columnType, row, column
1207 XmCR_DESELECT_COLUMN event, columnType, column
1208 XmCR_DESELECT_ROW event, rowType, row
1209 XmCR_EDIT_BEGIN rowType, columnType, row, column
1210 XmCR_EDIT_COMPLETE rowType, columnType, row, column
1211 XmCR_EDIT_CANCEL rowType, columnType, row, column, clipRect
1212 XmCR_EDIT_INSERT rowType, columnType, row, column, clipRect
1213 XmCR_RESIZE_ROW rowType, row
1214 XmCR_RESIZE_COLUMN columnType, column
1215 XmCR_SCROLL_ROW rowType, row
1216 XmCR_SCROLL_COLUMN columnType, column
1217 XmCR_SELECT_CELL event, rowType, columnType, row, column
1218 XmCR_SELECT_COLUMN event, columnType, column
1219 XmCR_SELECT_ROW event, rowType, row
1220 .ni
1222 .SS Inherited Resources
1223 Grid inherits the resources shown below. The Grid resets its
1224 default XmNshadow-Thickness to 2.
1226 .nf
1227 .ft B
1228 Resource From Resource From
1229 .ft P
1230 XmNaccelerators Core XmNinitialResourcePersist Core
1231 XmNancestorSensitive Core XmNinsertPosition Composite
1232 XmNbackground Core XmNmappedWhenManaged Core
1233 XmNbackgroundPixmap Core XmNnavagationType Manager
1234 XmNborderColor Core XmNnumChildren Composite
1235 XmNborderPixmap Core XmNscreen Core
1236 XmNborderWidth Core XmNsensitive Core
1237 XmNbottomShadowColor Manager XmNshadowThicknses Manager
1238 XmNbottomShadowPixmap Manager XmNstringDirection Manager
1239 XmNchildren Composite XmNtopShadowColor Manager
1240 XmNcolormap Core XmNtopShadowPixmap Manager
1241 XmNdepth Core XmNtranslations Core
1242 XmNdestroyCallback Core XmNtraversalOn Manager
1243 XmNforeground Manager XmNunitType Manager
1244 XmNheight Core XmNuserData Manager
1245 XmNhelpCallback Manager XmNwidth Core
1246 XmNhighlightColor Manager XmNx Core
1247 XmNhighlightPixmap Manager XmNy Core
1248 .fi
1250 .SS Grid Translations
1251 Grid defines the translations shown below.
1253 .nf
1254 .ft B
1255 Event Action Event Action
1256 .ft P
1257 BSelect Press XmLGridSelect(BEGIN) BExtend Motion XmLGridButtonMotion()
1258 BExtend Press XmLGridSelect(EXTEND) BToggle Motion XmLGridButtonMotion()
1259 BToggle Press XmLGridSelect(TOGGLE) BSelect Release XmLGridSelect(END)
1260 BSelect Motion XmLGridButtonMotion() BExtend Release XmLGridSelect(END)
1261 BDrag Press XmLGridDragStart()
1262 .fi
1264 .SS Grid Text Traverse Translations
1265 When the Grid widget enters traverse mode, it overrides its Text
1266 widget child's translations with those shown below.
1268 .nf
1269 .ft B
1270 Event Action
1271 .ft P
1272 KUp XmLGridTraverse(UP)
1273 MCtrl KPageDown XmLGridTraverse(PAGE_RIGHT)
1274 MShift KUp XmLGridTraverse(EXTEND_UP)
1275 MCtrl MShift KPageDown XmLGridTraverse(EXTEND_ PAGE_RIGHT)
1276 MCtrl KUp XmLGridTraverse(PAGE_UP)
1277 KTab XmLGridTraverse(RIGHT)
1278 KDown XmLGridTraverse(DOWN)
1279 MShift KTab XmLGridTraverse(LEFT)
1280 MShift KDown XmLGridTraverse(EXTEND_DOWN)
1281 KBeginLine XmLGridTraverse(TO_TOP)
1282 MCtrl KDown XmLGridTraverse(PAGE_DOWN)
1283 KEndLine XmLGridTraverse(TO_BOTTOM)
1284 KLeft XmLGridTraverse(LEFT)
1285 KHome XmLGridTraverse(TO_TOP)
1286 MShift KLeft XmLGridTraverse(EXTEND_LEFT)
1287 MCtrl KHome XmLGridTraverse(TO_TOP_LEFT)
1288 MCtrl KLeft XmLGridTraverse(PAGE_LEFT)
1289 KEnd XmLGridTraverse(TO_BOTTOM)
1290 KRight XmLGridTraverse(RIGHT)
1291 MCtrl KEnd XmLGridTraverse(TO_BOTTOM_RIGHT)
1292 MShift KRight XmLGridTraverse(EXTEND_RIGHT)
1293 KInsert XmLGridEdit()
1294 MCtrl KRight XmLGridTraverse(PAGE_RIGHT)
1295 KF2 XmLGridEdit()
1296 KPageUp XmLGridTraverse(PAGE_UP)
1297 KSelect Press XmLGridSelect(BEGIN)
1298 MShift KPageUp XmLGridTraverse(EXTEND_ PAGE_UP)
1299 MCtrl KSelect Press XmLGridSelect(TOGGLE)
1300 MCtrl KPageUp XmLGridTraverse(PAGE_LEFT)
1301 KSelect Release XmLGridSelect(END)
1302 MCtrl MShift KPageUp XmLGridTraverse(EXTEND_ PAGE_LEFT)
1303 KEntend Press XmLGridSelect(EXTEND)
1304 KPageDown XmLGridTraverse(PAGE_DOWN)
1305 KExtend Release XmLGridSelect(END)
1306 MShift KPageDown XmLGridTraverse(EXTEND_ PAGE_DOWN)
1307 KActivate XmLGridSelect(ACTIVATE)
1308 .fi
1310 .SS Grid Text Edit Translations
1311 When the Grid widget enters edit mode, it overrides its Text
1312 widget child's translations with those shown below.
1314 .nf
1315 .ft B
1316 Event Action Event Action
1317 .ft P
1318 KDown XmLGridEditComplete(DOWN) KCancel XmLGridEditCancel()
1319 MShift KTab XmLGridEditComplete(LEFT) KActivate XmLGridEditComplete()
1320 KTab XmLGridEditComplete(RIGHT) KUp XmLGridEditComplete(UP)
1321 .fi
1323 .SS Action Routines
1324 Grid defines the actions shown below.
1325 .IP XmLGridButtonMotion()
1326 Moves any active resize line or extends the current selection if needed.
1327 .IP XmLGridCursorMotion()
1328 Changes the cursor to a resize cursor if it is over a resize area.
1329 .IP XmLGridDragStart()
1330 Begins a drag of the selected cells if required.
1331 .IP XmLGridEdit()
1332 Enters the Grid into edit mode and begins an edit of the current focus cell.
1333 .IP XmLGridEditCancel()
1334 Cancels any cell edit in progress and returns the Grid to traverse mode.
1335 .IP XmLGridEditComplete(direction)
1336 Completes any edit in progress and traverses in the direction specified.
1337 .IP XmLGridSelect(mode)
1338 Begins or completes selection of the mode type given depending
1339 on the event passed to the action function.
1340 .IP XmLGridTraverse(direction)
1341 Traverses in the given direction from the current focus cell.
1342 If traversal is successful, the new focus cell will be made
1343 visible, scrolling the Grid if necessary.
1344 .SH "SEE ALSO"
1345 XmLCreateGrid(3X) XmLGridAddColumns(3X) XmLGridAddRows(3X)
1346 XmLGridColumnIsVisible(3X) XmLGridDeleteAllColumns(3X) XmLGridDeleteAllRows(3X) XmLGridDeleteColumns(3X) XmLGridDeleteRows(3X) XmLGridDeselectAllCells(3X)
1347 XmLGridDeselectAllColumns(3X) XmLGridDeselectAllRows(3X)
1348 XmLGridDeselectCell(3X) XmLGridDeselectColumn(3X) XmLGridDeselectRow(3X)
1349 XmLGridEditBegin(3X) XmLGridEditCancel(3X) XmLGridEditComplete(3X)
1350 XmLGridGetColumn(3X) XmLGridGetFocus(3X)
1351 XmLGridGetRow(3X) XmLGridGetSelectedCellCount(3X) XmLGridGetSelectedCells(3X)
1352 XmLGridGetSelectedColumnCount(3X) XmLGridGetSelectedColumns(3X)
1353 XmLGridGetSelectedRow(3X) XmLGridGetSelectedRowCount(3X)
1354 XmLGridGetSelectedRows(3X) XmLGridMoveColumns(3X) XmLGridMoveRows(3X)
1355 XmLGridRead(3X) XmLGridReadPos(3X) XmLGridRedrawAll(3X) XmLGridRedrawCell(3X)
1356 XmLGridRedrawColumn(3X) XmLGridRedrawRow(3X) XmLGridReorderColumns(3X)
1357 XmLGridReorderRows(3X) XmLGridRowColumnToXY(3X) XmLGridRowlsVisible(3X)
1358 XmLGridSelectAllCells(3X) XmLGridSelectAllColumns(3X) XmLGridSelectAllRows(3X)
1359 XmLGridSelectCell(3X) XmLGridSelectColumn(3X) XmLGridSelectRow(3X)
1360 XmLGridSetFocus(3X) XmLGridSetStrings(3X) XmLGridSetStringsPos(3X)
1361 XmLGridWrite(3X) XmLGridWritePos(3X) XmLGridXYToRowColumn(3X)