Book Contents Previous Chapter Next Chapter
This chapter describes grid views, viewable objects that display information in rows and columns. Before reading this chapter, you should be familiar with viewables.
Magic Cap defines class GridView to provide the basic behavior for viewable objects that display tabular information in rows and columns, or grids. Class GridView is abstract, so you will never create any objects of this class. Instead, you'll create objects of GridView subclasses. The most common subclass is ListView, which displays an object list in rows and columns.
When you create grid views, you'll specify the views and their related objects in your instance definition file. You'll rarely call any operations of class GridView. Instead, you'll simply specify the objects, and Magic Cap will call their operations when necessary.
When you define grid views, you'll use the grid view object's fields to specify its appearance and behavior. This section describes what to put in the fields of a grid view in your instance definition file.
The cellTextStyle field refers to a text style object that defines the appearance of the objects in the grid. Use the columnTitles field to indicate the headings for the column titles in the grid. You can use the emptyMessage field to refer to a message that will be shown if there is no information in the grid and if row lines are not being displayed (as indicated by the gridFlags field, described below).
Use the selectedColumn and selectedRow fields to indicate which column and row are currently highlighted. The titleTextStyle field refers to a text style object that defines the appearance of headings on the grid.
You'll use the gridFlags field to customize how the grid view works. The gridFlags field provides a wide range of options you can use when displaying information in the grid. The rest of this section describes the mask constants defined by Magic Cap for each of the grid flags.
There are several flags that control the precise appearance of headings, or titles, in the grid. The showColumnTitles and showRowTitles flags control whether the titles appear at all. Set showTitleLines if you want your grid view to draw a line under its column titles and a line to the right of its row titles. You can title the grid's columns with consecutive integers starting at 1 by using the showColumnTitleAsNumber flag, or as spreadsheet-style letters (that is, A, B, C, and so on) by using showColumnTitleAsLetter. You can title rows the same way by using showRowTitleAsLetter or showRowTitleAsNumber. Set gridViewCenteredTitle to have Magic Cap center the grid's column titles.
Set noPartialCellMask to ensure that cells are displayed only if there is enough room to show them completely. If you set grayTitleBackgroundMask Magic Cap will draw a gray background behind the grid titles.
Use showColumnLines and showRowLines to determine whether the grid should draw separating lines between adjacent columns and row. Set showExtraRowLines to draw lines between empty rows in the grid.
Use showCountMask to display in the title the number of rows in the grid. If you set removePluralMask and the grid contains only one row, Magic Cap will make the column titles singular by removing the last character if it is an s.
Several other grid flags are used only by list views. See the following section, List Views, for information about those flags.
When you define list views, you'll use the view object's fields to specify its appearance and behavior. As with grid views, you'll use the gridFlags field to customize how the list view works and appears. This section describes the mask constants defined by Magic Cap for each of the grid flags that affect list views.
Use selectModeMask if you want users to select items in the list view by touching them. Set useContainerListMask if you want the list view to get its list from its enclosing card. If you set this flag, Magic Cap will call on the list view's container (usually a card) to get list items for the list view.
Use keyboardScrollMask if you want your list view to automatically scroll to the row that matches a character typed by the user. Set the scrollToSelectedMask flag if the current scene should scroll to a particular location when the location's entry in the list is selected.
If you want your list view to always have one item selected, use alwaysOneSelectedMask. If no other entry is selected, Magic Cap will select the first entry.
If your list view displays a list of address cards, you can use setCurrentContactMask to ensure that the list view selection matches Magic Cap's current contact. Set dontTrackMask if your list view shouldn't change its selection when the user touches. Use showRemainingMask if you want the last line of the list view to indicate how many other items are in the list that won't fit in the display space. If you set this flag and the items do not all fit in the list view, the last line will read (and n more) where n is the number of additional items.
Use menuResizeHMask if the list view should adjust its width to accommodate the widest entry in the list. Set the useListElementPerCell flag if you want your list view to map list element to each cell rather than to rows. You can use this flag if you want your list view to display a different list object in each cell.
Use confirmOnSelectMask if you want the list view to call its Confirm operation whenever its selection changes. Use listViewArrowMask if you want Magic Cap to automatically place scroll arrows in the list view if there are too many items to fit. If you set this flag, don't set showRemainingMask, or your list view won't work properly.
When you declare a list view in your instance definition file, you can use column information flags to specify the appearance and behavior of the columns.
Set the valueIsAttribute flag if your list contains objects and this column should display an attribute of those objects. Set the valueIsTextInfo flag if you want your list view to display the text info of the list objects. If you set this flag, you can also set valueIsAbbreviated to use the abbreviated text info of the objects.
The remaining three column flags affect the appearance of information in the column. Use the forceCentered flag if you want the column contents to be drawn centered, or use the forceRightAligned flag if you want the contents to be right-aligned in the cells. Set the allowSpillRight flag if you want the column contents to spill over into the next cell when the cell is too small to display all its information and the adjacent cell is empty.
For more information, see the following topics in Magic Cap Class and Method Reference:
class GridView
fields:
cellTextStyle columnTitles emptyMessage gridFlags selectedColumn selectedRow
titleTextStyle
class ListView
Book Contents Previous Chapter Next Chapter