chapter">
chapter">
Defined in GridView.Def
Abstract
Inherits from Box, Scroller Uses extra
Class GridView provides the basic behavior and framework for a family of classes that display objects in rows and columns. Class GridView has one Subclass: class ListView. Class ListView is a popular class, and has several useful subclasses.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Class GridView is abstract. You'll never instantiate a grid view object. Intead, you'll use objects of one of GridView's subclasses, such as class ListView or class PeopleList. You might create a subclass of class GridView, though you're more likely to create subclasses of class ListView.
Instantiate: never Subclass: sometimes Call its methods: rarely
You will call the methods of class GridView only rarely. To use grid views, just put instances into your object definition files. The grid flags are more important to you than class GridView's methods. (The flags and other constants are described in the section on Flag Descriptions later in this chapter.)
Class GridView defines the following methods:
| Method | Description |
|---|---|
| Columns | |
| AddColumn | Add a column at the given index |
| ColumnFlags | Read the column flags from the flagsn extra field stored in extra (see Utilities.h for flags) |
| ColumnKey | Read the column key from the keyn extra field stored in extra |
| ColumnOffset | Get a column's offset from left edge, read from offsetn extra field |
| ColumnTitle | Read the specified line from columnTitles to get this column's title |
| ColumnType | Read the column's type from the typen extra field |
| ColumnWidth | Compute a column's width by subtracting its offset from the offset of the column to its right |
| HasColumn | Check if the grid view contains at least the given number of columns |
| RemoveColumn | Remove the column at index column |
| SetColumnFlags | Set the column flags in the flagsn extra field |
| SetColumnKey | Set the column key in the keyn extra field |
| SetColumnOffset | Set the column offset from left edge in the offsetn extra field |
| SetColumnTitle | Set the given line in columnTitles to the specified string |
| SetColumnType | Set the column type in the typen extra field |
| Rows | |
| HasRow | Check if the grid view contains at least the given number of rows |
| RowHeight | Get the height of a row using the view's textStyle |
| ShowSelection | Make selected row visible |
| Cells | |
| FirstCell | Get the row and column of the first cell |
| SelectedCell | Get the row and column of the selected cell |
| SetFirstCell | Scroll the grid view so the given cell is at the top left |
| SetSelectedCell | Set the selection to the cell at the given row and column |
| framework methods: | Drawing |
| DrawCell | Draw one cell |
| DrawColumnTitles | Draw titles at the top of the columns |
| DrawGridLines | Draw lines between columns and rows |
| DrawRow | Draw one row |
| DrawRowTitles | Draw titles at the left edge of the rows |
| DrawSelection | Draw the selected cell |
| Render | Render grid view to a full page |
| Calculating bounds | |
| CellBounds | Calculate the bounds of the given cell |
| ColumnBounds | Calculate the bounds of the given column |
| ColumnTitleBounds | Calculate the bounds of a single column's title |
| ColumnTitlesBounds | Calculate the bounds of all the column titles |
| ColumnTitleHeight | Calculate the title height, derived from titleTextStyle |
| GridBounds | Calculate the grid view's content bounds minus title areas |
| GridHeight | Calculate the grid view's content height minus column title area |
| GridWidth | Calculate the grid view's content width minus row title area |
| RowBounds | Calculate the bounds of the given row |
| RowTitleBounds | Calculate the bounds of the given row's title |
| RowTitleWidth | Calculate the width of the column containing the row titles |
| RowTitlesBounds | Calculate the bounds of all of the row titles |
| SelectedBounds | Calculate the bounds of the selection |
| TotalHeight | Get the sum of the heights of all rows |
| TotalWidth | Get the sum of the widths of all columns |
| Hit testing | |
| InsideCell | Check if the dot is inside the given cell |
| InsideColumn | Check if the dot is inside the given column |
| InsideColumnTitle | Get the number of the column is the dot is inside a column title; otherwise return 0 |
| InsideRow | Get true if the dot is inside the given row |
| InsideRowTitle | Get the number of the row if the dot is inside a row title; otherwise return 0 |
| Tracking touches | |
| TrackMoveColumn | Reorder column after tracking touch |
| TrackSelectCell | Select by cells |
| TrackSelectColumn | Select by columns |
| TrackSelectRow | Select by rows |
Class GridView defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| ColumnCount | Unsigned | Total number of columns |
| FirstColumn | Unsigned | Scrolled-to column (1-based) |
| LastColumn | Unsigned | Last visible column (might be only partially visible) |
| SelectedColumn | Unsigned | Column or cell's column |
| FirstRow | Unsigned | Scrolled-to row (1-based) |
| LastRow | Unsigned | Last visible row (might be only partially visible) |
| RowCount | Unsigned | Total number of rows |
| ConstantRowHeight | Boolean | False; override to return true for a performance improvement |
| SelectedRow | Unsigned | The selected row, or the selected cell's row |
| CellTextStyle | TextStyle | The text style to use to draw cells, from the cellTextStyle field |
| TitleTextStyle | TextStyle | The text style to use to draw titles, from the titleTextStyle field |
Class GridView defines the following fields:
| Field | Type | Description |
|---|---|---|
| Inherited from SingleLinkable: | ||
| next | Object | next item in view list |
| Inherited from Linkable: | ||
| previous | Object | previous item in view list |
| Inherited from Viewable: | ||
| superview | Viewable | container for this object |
| subview | Viewable | first object contained by this object |
| relativeOrigin | Dot | origin relative to superview |
| contentSize | Dot | size of content rectangle |
| viewFlags | Unsigned | property settings |
| labelStyle | TextStyle | text style of viewable's label |
| color | Unsigned | color of viewable's content |
| altColor | Unsigned | alternative color (used only by Control and DrawShadowedImage) |
| shadow | Shadow | shadow drawn with object |
| sound | Sound | sound associated with object |
| Inherited from HasBorder: | ||
| border | Border | the gridview's border |
| Inherited from ScrollableByMicron: | ||
| scrollOffset | Dot | stores the scroll position |
| Defined by GridView: | ||
| gridFlags | Flags | flags that control various aspects of the list view's appearance |
| cellTextStyle | TextStyle | also determines row height |
| columnTitles | Text | 1 line per title |
| emptyMessage | Text | shown if row count is 0 and no row lines |
| selectedColumn | Unsigned | selected column |
| selectedRow | Unsigned | selected row |
| titleTextStyle | TextStyle | used for both columns and rows |
Each column of a grid view needs four extra fields to describe it. The four fields are:
| offsetn | The position of the left edge of this column, given as the number of microns from the left side of the grid view. |
| keyn | The column's key. For ListViews, this is passed to TextInfo or to Attribute. |
| typen | The type of the data this column displays, to be passed to ValueToText. |
| flagsn | Additional flags that control how the column is displayed and specify what kind of information is in the column. |
Include one set of each of these fields for each column in your list view, and append the column number to the field names. For example, a list view with three columns would include 12 extra fields in its instance definition. Those fields would look like this:
// beginning of instance definition here
offset1: <2.0>;
key1: 7;
type1: 3.w; // kString
flags1: 2.w;
offset2: <34.0>;
key2: 3;
type2: 3.w; // kString
flags2: 0x000A.w;
offset3: <175.0>;
key3: 4;
type3: 3.w; // kString
flags3: 2.w;
offset4: <254.0>;
key4: 8;
type4: 7.w; // kObject
flags4: 0x000A.w;
The section in this chapter on flag descriptions lists the values you can use in the flags, type, and key fields For more information on these extra fields, also see the chapter on class ListView.
Class GridView uses four sets of constants. This section describes only the grid flags defined by class GridView.
For a description of the column flags, attribute codes, and type codes, see the chapter on class ListView. The chapter on class ListView also describes additional grid flags supported by ListView and its subclasses, but not by class GridView.
Class GridView defines a number of masks which it uses to get and set flags in the gridFlags field. These flags affect how a grid view object is drawn. They are described below. Class ListView also uses the gridFlags field. It defines an additional set of flags. See the chapter on class ListView for more information.
#define showCountMask 0x40000000
Set this flag if your grid view should display the number of rows in front of every column title. The DrawColumnTitles method checks this flag.
You can use this flag to create grid views like this one, from the word lists book:
The "17" in the title is the number of rows in the grid view, and hence the number of cities in the list.
#define showColumnTitles 0x10000000
Set this flag if your grid view should display its column titles. If you don't set this flag, GridView_Draw won't call DrawColumnTitles, so none of the flags used by that method will have any effect.
This flag is checked by the Draw method and by methods that compute column bounds, such as ColumnTitleBounds, ColumnTitleHeight, and ColumnTitlesBounds.
#define showColumnLines 0x02000000
Set this flag if your grid view should draw lines between columns. The DrawGridLines method checks this flag.
#define showRowLines 0x01000000
Set this flag if your grid view should draw lines between rows. The DrawGridLines method checks this flag.
The phone log is displayed using a subclass of GridView (class ContentListView), and draws lines between rows like this:
#define showExtraRowLines 0x00800000
Set this flag if your grid view should draw row lines between empty rows, in addition to lines between filled rows. The notebook's check list page uses an EditableList object that draws extra row lines, like this:
The Draw method checks this flag.
#define showTitleLines 0x00200000
Set this flag if your grid view should draw a line under its column titles and a line to the right of its row titles. The Draw method checks this flag.
#define showColumnTitleAsLetter 0x00008000
Set this flag if your grid view should title its columns with letters: A, B, C, and so on. The DrawColumnTitles method checks this flag, and calls the DrawTitleAsLetter method if it's set.
#define showColumnTitleAsNumber 0x00004000
Set this flag if your grid view should title its columns with numbers: 1, 2, 3, and so on. The DrawColumnTitles method checks this flag, and calls the DrawTitleAsNumber method if it's set.
#define showRowTitles 0x00002000
Set this flag if your grid view should show its row titles. The Draw methods checks this flag, and calls DrawRowTitles if it's set.
#define showRowTitleAsLetter 0x00001000
Set this flag if your grid view should title its rows with letters: A, B, C, and so on. The DrawRowTitles method checks this flag, and calls the DrawTitleAsLetter method if it's set.
Here's an example of lettered rows which uses the grid flags 0x12323400:
#define showRowTitleAsNumber 0x00000800
Set this flag if your grid view should title its row with numbers: 1, 2, 3, and so on. The DrawRowTitles method checks this flag, and calls the DrawTitleAsNumber method if it's set.
Here's an example of numbered rows, using the grid flags 0x1232200:
#define noPartialCellMask 0x00000200
Set this flag if your grid view shouldn't display cells that are only partly visible.
The LastColumn and LastRow methods checks this flag. These two methods both call a private routine that determines which cells of the grid view are visible. If this flag is set, cells that are partially on the screen won't be considered visible, and thus won't be drawn. If this flag is not set, cells that are partially on the screen will be drawn.
Here's an example that shows you how setting this flag changes which cells are visible. The top grid view does not set this flag; the bottom one does:
#define grayTitleBackgroundMask 0x00000100
Set this flag if your grid view's column titles should be displayed on a gray background. The DrawColumnTitles method checks this flag, and fills the column titles bounding box with rgbGray20 if it's set.
The phone's location list view (a subclass of GridView) sets this flag. That grid view looks like this:
#define gridViewCenteredTitle 0x00000080
Set this flag if your grid view's column titles should be centered. The DrawColumnTitles method checks this flag, and uses a centered style to draw column titles if it's set.
#define forPrintingMask 0x00000020
The system sets this flag for list views that are to be rendered for printing. The Render method checks this flag, and calls its inherited method if it's set. You probably won't need to set this flag yourself.
#define removePluralMask 0x00000004
Set this flag if your grid view's column titles should not be plural if they
contain only one row. The DrawColumnTitles method checks this flag. If it's
set, DrawColumnTitles removes an `s' character from the end of a column's
title. For example, it'll change a "ducklings" title to "duckling". It won't
perform more sophisticated changes, such as changing "children" to "child".