Home Screen manipulation routines
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.
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.
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.
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.
See also: HomeStore, HomeStorePair, HS_popEStack
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; }
See also: HomePushEStack, HomeStorePair, HS_popEStack
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.
See also: HomeStore, HS_pushEmptyFIFONode
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.
unsigned short HS_countFIFO (void); |
Returns the number of history pairs.
HS_countFIFO returns the number of entry/answer pairs in the history.
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.
See also: HS_pushFIFONode
void HS_freeAll (void); |
Clears the Home Screen history.
HS_freeAll clears the history, freeing all nodes. This function calls HS_freeFIFONode repeatedly.
See also: cmd_clrhome
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.
See also: HS_newFIFONode, HS_deleteFIFONode
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.
See also: HS_getEntry, HS_getFIFONode
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.
See also: HS_getAns, 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.
See also: HS_getEntry, HS_getAns
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.
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.
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 can not 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.
See also: HS_pushFIFONode, HomeStorePair
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.
See also: HS_pushEmptyFIFONode, HomeStorePair
typedef struct {
|
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.
See also: FIFO_NODE
typedef struct {
|
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.
See also: FIFO_ELEMENT