The <statline.h> Header File

Routines for manipulation of the status line

Functions

ST_angle
Sets the angle mode indicator in the status line.
ST_batt
Sets the battery low indicator in the status line.
ST_busy
Sets the BUSY indicator in the status line.
ST_eraseHelp
Redraws the status line.
ST_folder
Sets the folder name indicator in the status line.
ST_graph
Sets the graph mode indicator in the status line.
ST_helpMsg
Displays message in the status line.
ST_modKey
Sets the modifier key indicator in the status line.
ST_precision
Sets the precision mode indicator in the status line.
ST_progressBar
Creates a progress bar in the status line.
ST_progressDismiss
Removes a progress bar from the status line.
ST_progressIncrement
Increments the value of a progress bar.
ST_progressUpdate
Changes the value of a progress bar.
ST_readOnly
Sets the "read only" (or "locked") indicator in the status line.
ST_refDsp
Displays a system message in the status line.
ST_stack
Sets the history pairs indicator in the status line.

Predefined Types

Bool
An enumeration to describe true or false values.
SCR_RECT
A scructure for defining a rectangular area.
SCR_STATE
A structure for saving the state of the graphics system.
ST_ACTIVITIES
Contains status bar activity flags.
ST_FLAGS
An enumeration containing codes of status line indicators.
ST_PROGRESS_BAR
A structure describing a progress bar.
WIN_RECT
A structure for defining a rectangular area.
WINDOW
The main window-describing structure.

ST_angle

void ST_angle (short mode);

Sets the angle mode indicator in the status line.

ST_angle sets the angle mode indicator to RAD or DEG, depending of whether mode is ST_RAD or ST_DEG (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. Note that this command acts only to the displayed status; it would not change the actual current angle mode (use MO_digestOptions if you want to change angle mode).


ST_batt

void ST_batt (short mode);

Sets the battery low indicator in the status line.

ST_batt sets the battery low indicator to nothing, BATT with light background, or BATT with dark background, depending of whether mode is ST_BATT_OK, ST_BATT_LOW or ST_BATT_REPLACE (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line.


ST_busy

void ST_busy (short mode);

Sets the BUSY indicator in the status line.

ST_busy sets the program status indicator to idle, busy or paused, depending of whether mode is ST_IDLE, ST_BUSY or ST_PAUSED (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. In the idle mode, the number of entry/answer pairs in the history area would be displayed, else words "BUSY" or "PAUSE" would be displayed. If ST_busy is called with argument ST_NORMAL, the indicator would be erased. Note that the TIOS event handler always sets "BUSY" indicator before calling an event to an application, and clears it when the application returns from handling the event.

Note: Alternative mode names ACTIVITY_IDLE, ACTIVITY_BUSY and ACTIVITY_PAUSED known from DoorsOS will also be accepted, and these constants are defined in enum ST_ACTIVITIES.


ST_eraseHelp

short ST_eraseHelp (void);

Redraws the status line.

If the status flags indicate that a help message is being displayed, this function redraws the status line, effectively removing the message. Returns TRUE or FALSE, depending of whether redrawing was performed or not.


ST_folder

void ST_folder (const char *name);

Sets the folder name indicator in the status line.

ST_folder sets the folder name indicator to name, i.e. displays the given folder name (converted to uppercase letters) at the beginning of the status line. Note that this command acts only to the displayed status; it would not change the actual current folder (use routines for vat.h for changing the current folder).


ST_graph

void ST_graph (short mode);

Sets the graph mode indicator in the status line.

ST_angle sets the graph mode indicator to FUNC, PAR, POL, SEQ, 3D or DE, depending of whether mode is ST_FUNC, ST_PAR, ST_POL, ST_SQR, ST_3D or ST_DE (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. Note that this command acts only to the displayed status; it would not change the actual current graph mode.


ST_helpMsg

void ST_helpMsg (const char *msg);

Displays message in the status line.

ST_helpMsg displays the message msg in the status line, also setting a status flag indicating that a message is being displayed.

Deprecated alias: ST_showHelp


ST_modKey

void ST_modKey (short flags);

Sets the modifier key indicator in the status line.

ST_modKey sets the modifier key indicator to nothing, 2nd, shift, diamond, alpha, shifted alpha lock or alpha lock, depending of whehter mode is ST_NONE, ST_2ND, ST_SHIFT, ST_DIAMOND, ST_ALPHA, ST_SH_A_LOCK or ST_A_LOCK (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. This function has a very limited usage, because it is called very often from AutoInt 1, so if interrupts are enabled, the modifier key indicator will be changed very soon depending of actual state of the keyboard.


ST_precision

void ST_precision (short mode);

Sets the precision mode indicator in the status line.

ST_precision sets the precision mode indicator to AUTO, EXACT or APPROX, depending of whether mode is ST_AUTO, ST_EXACT or ST_APPROX (these constants are defined in enum ST_FLAGS). This indicator would be displayed in the status line. Note that this command acts only to the displayed status; it would not change the actual current precision mode.


ST_progressBar

AMS 2.00 or higher

void ST_progressBar (ST_PROGRESS_BAR *pb, long low, long high);

Creates a progress bar in the status line.

ST_progressBar creates a progress bar in the status line (excluding the busy indicator), representing values ranging from low to high. The progress bar will be stored into pb. The function also redraws the line at the top of the status line.

As an alternative to this function, you can fill an ST_PROGRESS_BAR structure manually. This gives you the possibility to create a progress bar in any window.

Here is an example (called "Progress Bar"):

// Progress bar example for TIGCC

// Define this to display the progress bar in a (large) window
//#define USE_WINDOW_PB

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define MIN_AMS 200           // Compile for AMS 2.00 or higher

#include <tigcclib.h>         // Include All Header Files

// Main Function
void _main(void)
{
  short j;

#ifdef USE_WINDOW_PB
  ST_PROGRESS_BAR spb = {NULL, {0, 0, 0, 0}, 0, 0, 100, 100, 0};
  WINDOW w;
  memcpy (&(spb.rect), ScrToWin (ScrRect), sizeof (WIN_RECT));
  spb.physwidth = spb.rect.x1 - spb.rect.x0 + 1;
  WinOpen (&w, &(spb.rect), WF_SAVE_SCR | WF_NOBORDER);
  spb.w = &w;
#else
  ST_PROGRESS_BAR spb;
  ST_progressBar (&spb, 0, 100); // Create the progress bar in spb. low=0, high=100.
                                 // It will be created in the status line.
#endif
  
  for (j = 0; j < 20; j++)
    {
      OSFreeTimer (USER_TIMER);
      OSRegisterTimer (USER_TIMER, 1);
      while (!OSTimerExpired (USER_TIMER)); // Wait a little...
      ST_progressIncrement (&spb, 1); // Increment the progress bar by 1/100.
    }
  ST_progressUpdate (&spb, 50); // Increment the progress bar up to 50/100.
  OSFreeTimer (USER_TIMER);
  OSRegisterTimer (USER_TIMER, 20);
  while (!OSTimerExpired (USER_TIMER)); // Wait for about 1 second...
  OSFreeTimer (USER_TIMER);
  ST_progressUpdate (&spb, 100); // Fill the progress bar entirely.
  
  GKeyIn (NULL, 0);
  ST_progressDismiss (&spb); // Remove the progress bar, redraw status line.
#ifdef USE_WINDOW_PB
  WinClose (&w);
#endif
}

See also: ST_progressDismiss, ST_progressIncrement, ST_progressUpdate, ST_PROGRESS_BAR


ST_progressDismiss

AMS 2.00 or higher

void ST_progressDismiss (ST_PROGRESS_BAR *pb);

Removes a progress bar from the status line.

ST_progressDismiss removes the progress bar pointed to by pb, and redraws the status line indicators. It is not necessary to call this function when you finish using a progress bar.

See also: ST_progressBar, ST_progressIncrement, ST_progressUpdate, ST_PROGRESS_BAR


ST_progressIncrement

AMS 2.00 or higher

void ST_progressIncrement (ST_PROGRESS_BAR *pb, long amount);

Increments the value of a progress bar.

ST_progressIncrement increments the progress bar pointed to by pb, by the quantity given in amount. It also displays the busy indicator in the status line.

If the resulting progress value is greater than the field logwidth of *pb, the bar will be filled completely. If amount is zero, the progress bar will simply be redrawn.

This function is not equivalent to ST_progressUpdate.

See also: ST_progressBar, ST_progressDismiss, ST_progressUpdate, ST_PROGRESS_BAR


ST_progressUpdate

AMS 2.00 or higher

void ST_progressUpdate (ST_PROGRESS_BAR *pb, long value);

Changes the value of a progress bar.

ST_progressUpdate updates the progress bar pointed to by pb, setting the progress to value. It also displays the busy indicator in the status line.

If value is greater than the logwidth field of *pb, the bar will be filled completely.

This function is not equivalent to ST_progressIncrement.

See also: ST_progressBar, ST_progressDismiss, ST_progressIncrement, ST_PROGRESS_BAR


ST_readOnly

void ST_readOnly (short mode);

Sets the "read only" (or "locked") indicator in the status line.

ST_readOnly sets the "read only" ("locked") indicator in the status line if the mode is non-zero, else resets the indicator. But note that this indicator appears only when you open a variable in a text editor, and that this routine does not set or change the read-only state of the text currently being edited. This function is called from TE_indicateReadOnly.


ST_refDsp

void ST_refDsp (short msg_no);

Displays a system message in the status line.

ST_refDsp displays various system messages (determined by msg_no) in the status line (this function calls ST_helpMsg). Here is the list of used messages:

1TYPE OR USE left right up down + [ENTER]=OK AND [ESC]=CANCEL
2USE up AND down TO OPEN CHOICES
3USE left right up down + [ENTER]=OK AND [ESC]=CANCEL
4TYPE + [ENTER]=OK AND [ESC]=CANCEL
5USE left right up down OR TYPE + [ESC]=CANCEL
6USE left right up down + [ENTER]=OK AND [ESC]=CANCEL, OR DRAG
7DATA PLACED IN VARIABLE SYSDATA
8DATA PLACED IN HOME SCREEN HISTORY
9[ENTER]=OK AND [ESC]=CANCEL
10empty
11USE left right + [ENTER]=OK AND [ESC]=CANCEL
12USE left right + [ENTER]=OK AND [ESC]=CANCEL
13USE [2ND] [KEYS] OR [ESC]=CANCEL


ST_stack

void ST_stack (short index, short total);

Sets the history pairs indicator in the status line.

ST_stack sets the displayed number of entry/answer pairs in the history area to index/total. This indicator is displayed in the status line only if the current program activity status (set by ST_busy) is ST_IDLE. Note that this command acts only on the displayed status; it does not change the actual number of entries in the history area, nor the capacity of the history area.


ST_ACTIVITIES

enum ST_ACTIVITIES {ACTIVITY_IDLE, ACTIVITY_BUSY, ACTIVITY_PAUSED, ACTIVITY_NORMAL};

Contains status bar activity flags.

ST_ACTIVITIES is enumerated type which contains some alias names known from DoorsOS.


ST_FLAGS

enum ST_FLAGS {ST_IDLE = 0, ST_BUSY = 1, ST_PAUSE = 2, ST_CLEAR = 3, ST_NORMAL = 3, ST_NOTHING = 0, ST_BATT = 1, ST_BATT_DARK = 2, ST_BATT_OK = 0, ST_BATT_LOW = 1, ST_BATT_REPLACE = 2, ST_RAD = 0, ST_DEG = 1, ST_FUNC = 0, ST_PAR = 2, ST_POL = 3, ST_SEQ = 4, ST_3D = 5, ST_DE = 6, ST_NONE = 0, ST_2ND = 1, ST_SHIFT = 2, ST_DIAMOND = 4, ST_ALPHA = 8, ST_SH_A_LOCK = 16, ST_A_LOCK = 32, ST_AUTO = 0, ST_EXACT = 1, ST_APPROX = 2};

An enumeration containing codes of status line indicators.

ST_FLAGS is an enumeration which contains codes of various modes which are possible to set into the status line using various functions defined in the statline.h header file.

Some of these values (like ST_BATT_DARK) are deprecated, and they are included only for backwards compatibility.


ST_PROGRESS_BAR

AMS 2.00 or higher

typedef struct {
WINDOW *w; /* parent window */
WIN_RECT rect; /* scroll bar area */
long value; /* current progress */
long low, high; /* minimum and maximum values for progress */
long logwidth; /* equal to high-low */
short physwidth; /* equal to rect.x1-rect.x0+1 */
} ST_PROGRESS_BAR;

A structure describing a progress bar.

ST_PROGRESS_BAR describes a progress bar, which is used with the following functions: ST_progressBar, ST_progressDismiss, ST_progressIncrement, ST_progressUpdate.

You do not need to fill the structure by hand; this is done automatically by ST_progressBar. In addition to this, this function already draws the outline of the progress bar.
However, if you want to fill an ST_PROGRESS_BAR structure by hand, you can do it easily:

Beware that the functions dealing with progress bars are very slow. They take more than 20 ms, that is to say half of the time between two timer ticks. You can go up to a bit less than 1 second when a progress bar taking the full screen of the 92+ is filled. Filling the screen pixel by pixel with a double loop using logical operations with masks, or better, bit operations, is up to about 10 times faster...

So it is not a good idea to use these functions if you want to clock the process whose progress is represented by the bar. Take a look at the "Progress Bar" example for an implementation demonstrating this pitfall:

// Progress bar example for TIGCC

// Define this to display the progress bar in a (large) window
//#define USE_WINDOW_PB

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define MIN_AMS 200           // Compile for AMS 2.00 or higher

#include <tigcclib.h>         // Include All Header Files

// Main Function
void _main(void)
{
  short j;

#ifdef USE_WINDOW_PB
  ST_PROGRESS_BAR spb = {NULL, {0, 0, 0, 0}, 0, 0, 100, 100, 0};
  WINDOW w;
  memcpy (&(spb.rect), ScrToWin (ScrRect), sizeof (WIN_RECT));
  spb.physwidth = spb.rect.x1 - spb.rect.x0 + 1;
  WinOpen (&w, &(spb.rect), WF_SAVE_SCR | WF_NOBORDER);
  spb.w = &w;
#else
  ST_PROGRESS_BAR spb;
  ST_progressBar (&spb, 0, 100); // Create the progress bar in spb. low=0, high=100.
                                 // It will be created in the status line.
#endif
  
  for (j = 0; j < 20; j++)
    {
      OSFreeTimer (USER_TIMER);
      OSRegisterTimer (USER_TIMER, 1);
      while (!OSTimerExpired (USER_TIMER)); // Wait a little...
      ST_progressIncrement (&spb, 1); // Increment the progress bar by 1/100.
    }
  ST_progressUpdate (&spb, 50); // Increment the progress bar up to 50/100.
  OSFreeTimer (USER_TIMER);
  OSRegisterTimer (USER_TIMER, 20);
  while (!OSTimerExpired (USER_TIMER)); // Wait for about 1 second...
  OSFreeTimer (USER_TIMER);
  ST_progressUpdate (&spb, 100); // Fill the progress bar entirely.
  
  GKeyIn (NULL, 0);
  ST_progressDismiss (&spb); // Remove the progress bar, redraw status line.
#ifdef USE_WINDOW_PB
  WinClose (&w);
#endif
}

Return to the main index