Apple Newton Utilities User's Guide download pdf (Page 486)

100

101

CHAPTER 11

Data Storage and Retrieval

11-54 Using Newton Data Storage Objects

■ getting the number of entries in cursor data

■ getting an index key from the cursor

■ copying the cursor

Getting a Cursor 11

Cursor objects are returned by the Query method. For more information, see

“Using Queries” beginning on page 11-38.

Testing Validity of the Cursor 11

When a storage card is inserted or a soup is created, union soups include new soups

in the union automatically as is appropriate. A cursor on a union soup may not be

able to include a new soup when the new soup’s indexes do not match those present

for the other soups in the union. In particular, this situation can occur when

■ The new soup does not have the index speciﬁed in the indexPath of the query

spec used to generate the cursor.

■ The query spec used to generate the cursor included a tagSpec and the new

soup does not have the correct tags index.

In such cases, the cursor becomes invalid. An invalid cursor returns

nil when sent

messages such as

Next, Prev, Entry, and so on. Note that a valid cursor returns

nil when it receives a message that positions it outside of the range of valid

entries. (For an example, see the text accompanying Figure 11-6 on page 11-46.)

You can test the cursor’s validity by invoking the

Status cursor method. This

method returns the

'valid symbol for cursors that are valid and returns the

'missingIndex symbol when a soup referenced by the cursor is missing an

index. Your application needs to call this method when it receives either of the

'soupEnters or 'soupCreated soup change notification messages. If the

Status method does not return the 'valid symbol, the application must correct

the situation and recreate the cursor.

For a detailed description of the

Status cursor method, see the section “Query

and Cursor Methods” (page 9-60) in Newton Programmer’s Reference. For a

discussion of soup change notiﬁcation messages, see the section “Callback

Functions for Soup Change Notiﬁcation” (page 9-14) in Newton Programmer’s

Reference.

Getting the Entry Currently Referenced by the Cursor 11

To obtain the entry currently referenced by the cursor, send the Entry message to

the cursor, as shown in the following code fragment:

// assume myCursor is valid cursor returned from a query

local theEntry := myCursor:Entry();

1 2 ... 481 482 483 484 485 486 487 488 489 490 491 ... 941 942

Comments to this Manuals

No comments

Apple Newton Utilities User's Guide Page 486

Comments to this Manuals

Related products and manuals for Software Apple Newton Utilities