homescr.h

The <homescr.h> Header File

Home Screen manipulation routines

Functions

HomeAlone: Checks if the Home Screen is active in full-screen mode.
HomeExecute: Sends a command to the Home Screen.
HomePushEStack: Creates and draws a new history pair with given contents.
HomeStore: Creates a new history pair with contents from the expression stack.
HomeStorePair: Creates a new history pair with given contents.
HS_chopFIFO: Deletes all history items which exceed the limit.
HS_countFIFO: Returns the number of history pairs.
HS_deleteFIFONode: Deletes a history entry/answer pair.
HS_freeAll: Clears the Home Screen history.
HS_freeFIFONode: Frees a FIFO node.
HS_getAns: Returns the handle of a Home Screen answer.
HS_getEntry: Returns the handle of a Home Screen entry.
HS_getFIFONode: Returns the handle of a history pair.
HS_newFIFONode: Allocates memory for a new FIFO node.
HS_popEStack: Pops the entire expression stack into memory.
HS_pushEmptyFIFONode: Inserts a new almost-empty FIFO node into the history.
HS_pushFIFONode: Inserts a new filled FIFO node into the history.

Global Variables

HS_FirstFIFONodeHandle: The handle of the FIFO node related to the first entry of the Home Screen history.
HS_MaxExpressions: The maximum number of expressions allowed in the home screen.

Constants

H_NULL: A null-handle value.

Predefined Types

Bool: An enumeration to describe true or false values.
ESQ: Represents a quantum within an expression.
FIFO_ELEMENT: A structure describing a single entry or answer element in the history.
FIFO_NODE: Describes an entry/answer pair in the history.
HANDLE: Represents a handle associated with an allocated memory block.
MULTI_EXPR: Describes a multi-expression, which is processed as a separate expression stack.

Note: In most cases, this header file is used to store expressions in the Home Screen history. For this purpose, use the HomeStore and HomeStorePair functions. They are much less complicated than the other functions manipulating the history.

HomeAlone

AMS 2.00 or higher

unsigned short HomeAlone (void);

Checks if the Home Screen is active in full-screen mode.

HomeAlone returns TRUE if the Home Screen is active on a full screen and events are not captured, and FALSE otherwise.

HomeExecute

void HomeExecute (const char *Command, unsigned short ComLen);

Sends a command to the Home Screen.

This function sends an ordinary ANSI C string pointed to by Command (which does not have to be zero-terminated) to the Home Screen application, which will execute it exactly as if the string was typed in from the keyboard into the Home Screen entry line. ComLen must be smaller or equal to the length of Command.

HomePushEStack

void HomePushEStack (void);

Creates and draws a new history pair with given contents.

HomePushEStack is a very powerful command which lets you store expressions straight to the history.

The expression (not a multi-expression) which you want to store to the history has to be placed at the top of the expression stack. This function will pop it off of the estack and into the history. It will be used as both entry and answer, but it will not be simplified.

The result of using this call is that memory is allocated, so garbage collection may occur. After your program exits, the allocated memory will remain allocated, which is perfectly normal. However, kernels like DoorsOS, TeOS, and PreOS (but not UniversalOS) have a feature that frees all handles left unfreed by kernel programs. This feature is smart and first checks if a handle is that of a variable, but older kernels do not check if it is a history item.

For kernel-based programs, DoorsOS and TeOS will free the handles for the newly stored item, and when your program exits, the calculator will crash! PreOs 0.62 or higher detects the history handles and handles them correctly.

HomePushEStack calls HS_newFIFONode and HS_pushEmptyFIFONode to create the new history item.

Note: HomePushEStack redraws the home screen if it is the active application, which it most likely is. To circumvent this, use HomeStore.

HomeStore

void HomeStore (void);

Creates a new history pair with contents from the expression stack.

HomeStore performs the same operation as HomePushEStack. However, the visuals for storing something to the history with HomePushEStack will be done immediately, over top of your program's visuals, if the home screen is the current application, which it most likely is. This function suppresses this.

However, HomeStore still displays a message in the status bar saying "DATA PLACED IN HOME SCREEN HISTORY," and turns on the busy indicator.

HomeStore is implemented in assembly, using the following code as a starting point:

CALLBACK void TempHook(EVENT *ev)
{
  ev->Type = CM_IDLE;
}

void HomeStore(void)
{
  EVENT_HANDLER temp = EV_hook;
  EV_hook = TempHook;
  HomePushEStack ();
  EV_hook = temp;
}

HomeStorePair

void HomeStorePair (HANDLE Entry, HANDLE Ans);

Creates a new history pair with given contents.

HomeStorePair creates a new Home Screen history pair with a given entry and answer part. Entry and Ans have to point to multi-expressions (see MULTI_EXPR). They may be the same handles; in this case, the same expression will be used on both sides of the screen.

HomeStorePair first uses HS_newFIFONode to allocate memory for a new FIFO node, then fills the Expr fields of the entry and answer elements with Entry and Ans, and then calls HS_pushEmptyFIFONode. If HS_pushEmptyFIFONode throws an error, it calls HS_freeFIFONode to free all handles, even Entry and Ans.

In any case, the expressions pointed to by Entry and Ans should not be modified after calling this function. In fact, the two handles then belong to the operating system, and should not be used any more.

Note: It seems that the handles Entry and Ans should be allocated with HeapAlloc (or HeapAllocThrow), and should not be locked. Be sure to read the notes about HS_pushEmptyFIFONode as well.

HS_chopFIFO

void HS_chopFIFO (void);

Deletes all history items which exceed the limit.

HS_copyFIFO deletes all Home Screen history pairs which exceed the limit set by the user. It is called internally by HS_pushFIFONode, so usually you do not need to call it yourself.

HS_countFIFO

unsigned short HS_countFIFO (void);

Returns the number of history pairs.

HS_countFIFO returns the number of entry/answer pairs in the history.

HS_deleteFIFONode

HANDLE HS_deleteFIFONode (HANDLE Node);

Deletes a history entry/answer pair.

HS_deleteFIFONode deletes the history pair associated with Node, and returns the handle of the next history item in the linked list of FIFO nodes. To do this, it removes the node from the linked list, and then calls HS_freeFIFONode.

HS_freeAll

void HS_freeAll (void);

Clears the Home Screen history.

HS_freeAll clears the history, freeing all nodes. This function calls HS_freeFIFONode repeatedly.

HS_freeFIFONode

void HS_freeFIFONode (HANDLE Node);

Frees a FIFO node.

HS_freeFIFONode frees the node pointed to by Node, including the expressions it contains. The node should have been allocated with HS_newFIFONode. This function takes into account that the handles for the entry and answer may be the same.

This function is called by HS_deleteFIFONode and HS_freeAll. You should call it yourself only if you want to free a node you have allocated yourself, but which you could not insert into the history using HS_pushFIFONode.

HS_getAns

HANDLE HS_getAns (unsigned short Index);

Returns the handle of a Home Screen answer.

HS_getAns returns a handle to the answer part of the Home Screen history pair with index Index, where Index is a value between 1 and 99 and has the same meaning as the parameter of the TI-Basic 'ans' pseudo-function. If the answer does not exist, HS_getAns returns H_NULL. This happens in three conditions

The entry/answer pair does not exist.
The answer is a message like "Done" that comes after an executed program.
The answer is an error message (i.e. ERROR_MSG_TAG is present in it)

The returned handle contains a "multi-expression"; see MULTI_EXPR and HS_getEntry for more info.

HS_getEntry

HANDLE HS_getEntry (unsigned short Index);

Returns the handle of a Home Screen entry.

HS_getEntry returns a handle to the entry part of the Home Screen history pair with index Index, where Index is a value between 1 and 99 and has the same meaning as the parameter of the TI-Basic 'entry' pseudo-function. If the entry does not exist, HS_getEntry returns H_NULL.

The returned handle contains a "multi-expression". A multi-expression is an expression consisting of multiple expressions seperated by NEXTEXPR_TAG and ending in ENDSTACK_TAG. See MULTI_EXPR for more info.

Even if the multi-expression contains only one expression and therefore has no NEXTEXPR_TAGs in it, it will still have an ENDSTACK_TAG.

The handle returned by this funtion is valid input for HToESI and Parse2DMultiExpr.

HS_getFIFONode

HANDLE HS_getFIFONode (unsigned short Index);

Returns the handle of a history pair.

This function returns the handle of an entry/answer pair in the Home Screen history. Dereferencing this handle using HeapDeref or HLock returns a pointer to a FIFO_NODE structure containing the handles of the entry and answer and some additional information.

HS_newFIFONode

HANDLE HS_newFIFONode (void);

Allocates memory for a new FIFO node.

HS_newFIFONode simpy allocates 56 bytes for a FIFO_NODE structure and sets them all to zero. It throws an error if there is not enough memory.

HS_popEStack

HANDLE HS_popEStack (void);

Pops the entire expression stack into memory.

HS_popEStack allocates a block in memory, pops the entire expression stack into the allocated block, and returns a handle which points to it. More precisely, it creates a MULTI_EXPR structure holding the expression stack. If there is not enough memory, it throws an error. See NG_execute for an example of usage. The returned handle is allocated with HeapAllocHigh, and is therefore intended to be temporary. However, it is unlocked.

This function copies everything from bottom_estack to top_estack (including both bottom_estack and top_estack), and resets top_estack to bottom_estack. This means that the size of the allocated block is top_estack - bottom_estack + 3 (because the MULTI_EXPR structure reserves two bytes for the size). By changing bottom_estack temporarily, it is theoretically possible to set the block which is to be popped off manually. However, you need to take care of the requirement that bottom_estack has to point to an ENDSTACK_TAG quantum.

This function is intended to copy an expression into memory so that it can be pushed to the Home Screen using HS_pushFIFONode or one of its wrapper functions.

HS_pushEmptyFIFONode

void HS_pushEmptyFIFONode (HANDLE Node);

Inserts a new almost-empty FIFO node into the history.

HS_pushEmptyFIFONode inserts the entry/answer pair identified by Node into the linked list of FIFO nodes. Node must contain a handle to a FIFO_NODE structure, but only the Expr fields of the entry and answer need to be filled. It should have been allocated using HS_newFIFONode.

This function first fills the structure pointed to by Node, then calls HS_pushFIFONode to insert the new node. Unfortunately, it also calls ST_stack from statline.h to redraw the history status line indicator of the Home Screen, which cannot be prevented using PortSet or the method used in HomeStore. In theory, it is possible to fill the structure by hand, but this is very tedious.

Note: The address of the HS_pushEmptyFIFONode function is not in the jump table of any AMS version up to 2.05, and probably will never be. Getting the address of this function is implemented using a very dirty hack. However, it is the main function for storing items in the Home Screen history, so you probably cannot avoid it unless you want to fill the FIFO_NODE structure yourself. An error is thrown if the address of this function could not be determined.

HS_pushFIFONode

void HS_pushFIFONode (HANDLE Node);

Inserts a new filled FIFO node into the history.

HS_pushFIFONode inserts the entry/answer pair identified by Node into the linked list of FIFO nodes. Node must contain a handle to a FIFO_NODE structure, which needs to be filled completely except for the Prev and Next fields. It should have been allocated using HS_newFIFONode.

This function calls HS_chopFIFO to remove the last history pair if needed. It may throw an error if inserting the node was not possible.

HS_FirstFIFONodeHandle

AMS 2.04 or higher

const HANDLE HS_FirstFIFONodeHandle;

The handle of the FIFO node related to the first entry of the Home Screen history.

Warning: performing inappropriate changes to HS_FirstFIFONodeHandle may cause strange things on your calculator...

HS_MaxExpressions

AMS 2.04 or higher

const unsigned short HS_MaxExpressions;

The maximum number of expressions allowed in the home screen.

Warning: performing inappropriate changes to HS_MaxExpressions may cause strange things on your calculator...

FIFO_ELEMENT

typedef struct {
short ScreenLeft;
long ScreenBottom;
long XStart;
unsigned short Width;
unsigned short Height;
short Top;
HANDLE Expr;
short TooLong;
short PrettyPrint;
unsigned short Exp;
unsigned short Fix;

} FIFO_ELEMENT;

A structure describing a single entry or answer element in the history.

FIFO_ELEMENT is a structure used by the TIOS to describe a single entry or answer on the screen. It is included twice in the FIFO_NODE structure. In most cases, you do not need to access the individual fields of this structure directly.

Expr contains a handle to the actual expression (a multi-expression, see MULTI_EXPR). You can fill the Width and Height fields using the Parms2D function. You should also know that the values for the Fix and Exp fields need to be one less than the values in MO_OPTIONS.

FIFO elements are displayed using Parse2DMultiExpr, and then Print2DExpr if PrettyPrint is TRUE, or WinCharXY otherwise.

FIFO_NODE

typedef struct {
FIFO_ELEMENT Entry;
FIFO_ELEMENT Ans;
HANDLE Prev;
HANDLE Next;

} FIFO_NODE;

Describes an entry/answer pair in the history.

FIFO_NODE describes an entry/answer pair (a node) in the Home Screen history. Usually, you do not need to access the fields of this structure directly.

All nodes are kept in a bidirectionally linked list; the Prev and Next fields contain handles to the previous and next nodes, respectively.

The Expr fields of the Entry and Ans fields of this structure may contain the same handles.