GUI Function Glossary

C: void Add_Character( int textbox_reference, int character )
4th: Add_Character ( n1 \ n2 -- | n1 = textbox_reference, n2 = characrer )

Type: Function

Input Parameters:

• textbox_reference – A 16 bit reference to a textbox object.
• character -– A 16 bit character to be added to the textbox object. Valid values are from 0 to 255.

A method that passes a message to the slave processor telling the slave to add a character to a textbox. The character is added to the end of the string in the textbox. The character is rendered only if the RENDER property of the textbox is set. Refresh or Redraw must be called on the screen containing the textbox after character is added to display the character. Possible errors include: INVALID_TEXTBOX. Non ascii characters may also be added to display additonal symbols and bar graphs. The following figure displays all of the characters of the built-in font. Note that the first row of characters are bars of white pixels that are the same width as the black bars that are shown in the second row. The black and white bars are useful for drawing and erasing horizontal bar graphs.

Add_Character( textboxTitle, 0x64 ); // add ascii d to the textbox

textboxTitle @ 0x64 Add_Character \ add ascii d to the textbox

Libraries: library.c , library.4th

See also: Delete_Character

C: void Add_Data ( int plot_reference, int data )
4th: Add_Data( n1 \ n2 -- | n1 = plot_reference, n2 = data )

Type: Function

Input Parameters:

• plot_reference – A 16 bit reference to a plot object.
• data – A 16 bit integer to be added to the plot object. Valid values are from 0 to the height of the plot object in pixels. The data represents the distance in pixels as measured from the top edge of the plot. The origin of a plot is the upper left corner of the plot object.

A method that passes a message to the slave processor telling the slave to add a single data value into a plot object. Data is added to the next position in the circular plot buffer. The data value represents the distance in pixels as measured from the top edge of the plot (the y coordinate). The x coordinate is the position of the data value in the buffer. The x coordinate can not be changed or specified. Refresh must be called after data is added to re-render the plot. The plot is rendered from left to right like an oscilloscope trace. Possible errors include: INVALID_PLOT and DATA_OUT_OF_RANGE.

Add_Data( plotVoltage, 12 );

plotVoltage @ 12 Add_Data

Libraries: library.c , library.4th

C: AVAILABLE_HEAP_SPACE
4th: AVAILABLE_HEAP_SPACE

Type: Constant
Return Value: Integer

The name of a GUI Toolkit property that returns the available bytes remaining in the GUI Heap. This property is read only.

longHeapSpace = Get_Property(GUI_TOOLKIT(),AVAILABLE_HEAP_SPACE);

GUI_TOOLKIT AVAILABLE_HEAP_SPACE Get_Property heapSpace 2!

Libraries: library.c , library.4th

C: BACKLIGHT_ON
4th: BACKLIGHT_ON

Type: Constant
Return Value: Integer

The name of a display property that controls the backlight on the display. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. BACKLIGHT_ON is initialized to GUI_TRUE by Initialize_GUI.

Set_Property(GUI_DISPLAY(),BACKLIGHT_ON,GUI_FALSE);

GUI_DISPLAY BACKLIGHT_ON GUI_FALSE Set_Property

Libraries: library.c , library.4th

C: BEEP_DUTY_PERIOD
4th: BEEP_DUTY_PERIOD

Type: Constant
Return Value: Integer

The name of a read only buzzer property that returns the duty and period used to produce the current BEEP_NOTE. The duty is initialized to 6 and the period is initialized to 199 (corresponding to a 2093 Hz note or C7) when GUI Toolkit is instantiated. The duty is returned in the 16 least significant bits and the period is returned in the 16 most significant bits.

longDutyPeriod = Get_Property ( GUI_BUZZER(), BEEP_DUTY_PERIOD );
intDuty = (int)(longDutyPeriod & 0xFFFF);
intPeriod = (int)(longDutyPeriod >> 16);

GUI_BUZZER BEEP_DUTY_PERIOD Get_Property ( duty \ period )

Libraries: library.c , library.4th

See also: BEEP_NOTE

C: BEEP_NOTE
4th: BEEP_NOTE

Type: Constant
Return Value: Integer

The name of a buzzer property that sets the note and hence the frequency of the buzzer playback. BEEP_NOTE is initialized to 96 which is the midi note for C7 when the GUI Toolkit is initialized. Possible values of the beeper note range from 36 (which is the midi note for C2) to 108 (which is the midi note for C8). The note will not change while the buzzer is on.

Set_Property ( GUI_BUZZER(), BEEP_NOTE, 84 ); // Set the note to C6.

GUI_BUZZER BEEP_NOTE 84 Set_Property \ Set the buzzer note to C6.

Libraries: library.c , library.4th

See also: BEEP_DUTY_PERIOD

C: BEEP_ON_HOLD
4th: BEEP_ON_HOLD

Type: Constant
Return Value: Integer

The name of a button property that beeps the buzzer when a button is held. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. BEEP_ON_HOLD is initialized to GUI_FALSE when a button is instantiated.

Set_Property ( buttonDelete, BEEP_ON_HOLD, GUI_TRUE );

ButtonDelete @ BEEP_ON_HOLD GUI_TRUE Set_Property

Libraries: library.c , library.4th

See also: BEEP_ON_RELEASE, BEEP_ON_PRESS

C: BEEP_ON_PRESS
4th: BEEP_ON_PRESS

Type: Constant
Return Value: Integer

The name of a button property that beeps the buzzer when the button is pressed. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. BEEP_ON_PRESS is initialized to GUI_TRUE when a button is instantiated.

Set_Property ( buttonPause, BEEP_ON_PRESS, GUI_TRUE );

buttonPause @ BEEP_ON_PRESS GUI_TRUE Set_Property

Libraries: library.c , library.4th

See also: BEEP_ON_RELEASE, BEEP_ON_HOLD

C: BEEP_ON_RELEASE
4th: BEEP_ON_RELEASE

Type: Constant
Return Value: Integer

The name of a button property that beeps the buzzer when the button is released. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. BEEP_ON_RELEASE is initialized to GUI_FALSE when a button is instantiated.

Set_Property ( buttonPause, BEEP_ON_RELEASE, GUI_TRUE );

buttonPause @ BEEP_ON_RELEASE GUI_TRUE Set_Property

Libraries: library.c , library.4th

See also: BEEP_ON_PRESS, BEEP_ON_HOLD

C: BEEP_TIME
4th: BEEP_TIME

Type: Constant
Return Value: Integer

The name of a buzzer property that controls the length of time of a beep. The units of BEEP_TIME are milliseconds. The default BEEP_TIME is 3 milliseconds. The range of BEEP_TIME is from 0 to 65535 or 0 to 65.5 seconds. While the buzzer is on when calling BUZZ, the GUI Toolkit is not looking for touchscreen touches or executing commands. For longer duration beeps, manually turn the buzzer on and off using the BUZZER_ON property.

Set_Property(GUI_BUZZER(), BEEP_TIME, (long) 20); // Set beep to 20 ms.

GUI_BUZZER BEEP_TIME 20 u>d Set_Property \ Set beep time to 20 ms.

Libraries: library.c , library.4th

See also: BUZZER_ON

C: BIT_DEPTH
4th: BIT_DEPTH

Type: Constant
Return Value: Integer

The name of a read only display property that indicates the number of bits used to decribe a pixel (a single dot on the screen). Possible values of the bit depth are 1, 4, or 8. The bit depth is set with an input parameter to Initialize_GUI.

LongBitDepth = Get_Property ( GUI_DISPLAY(), BIT_DEPTH );

GUI_DISPLAY BIT_DEPTH Get_Property D>S bitDepth !

Libraries: library.c , library.4th

C: BIT_DEPTH_DOES_NOT_MATCH
4th: BIT_DEPTH_DOES_NOT_MATCH

Type: Constant
Return Value: Integer

The name of an error that indicates the bit depth of the image does not match the bit depth of the display.

Set_Property(graphicPump, IMAGE, SYRINGE_PUMP_BMP);
if((Read_Error() >> 16) == BIT_DEPTH_DOES_NOT_MATCH)
{
 printf("Image bit depth must equal bit depth of display.\n");
 Clear_Error();
}

graphicPump @ IMAGE SYRINGE_PUMP_BMP Set_Property
Read_Error NIP BIT_DEPTH_DOES_NOT_MATCH = \ drop command
IF
 CR ." Image bit depth must equal bit depth of display."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: BLACK
4th: BLACK

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to black if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)BLACK);

GUI_SCREEN SCREEN_BACKGROUND BLACK u>d Set_Property

Libraries: library.c , library.4th

C: BLANK_DISPLAY
4th: BLANK_DISPLAY

Type: Constant
Return Value: Integer

The name of a display property that blanks the display. This does not clear or unload objects from the visible screen. This is useful as a screen saver. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. BLANK_DISPLAY is initialized to GUI_FALSE by Initialize_GUI.

Set_Property(GUI_DISPLAY(), BLANK_DISPLAY, GUI_TRUE);

GUI_DISPLAY BLANK_DISPLAY GUI_TRUE Set_Property

Libraries: library.c , library.4th

C: BLOCK_ON_HOLD
4th: BLOCK_ON_HOLD

Type: Constant
Return Value: Integer

The name of a button property that when set, disables the servicing touchscreen events until a RELEASE_EVENT occurs and the GUI_TOOLKIT() property SERVICE_EVENTS is set to GUI_TRUE. Set this button property for repeating buttons. The final line of the button's hold event procedure must re-enable the servicing of events by setting the GUI_TOOLKIT() property SERVICE_EVENTS to GUI_TRUE.

extern xaddr Delete_Event_Procedure_xaddr; // Create function ptr.
void Delete_Event_Procedure ( void )
 {
 // The Delete Button Event Procedure code would go here.
 
 // Reset SERVICE_EVENTS to GUI_TRUE to re-enable event servicing.
 // This must be the last thing done by the event procedure.
 Set_Property( GUI_TOOLKIT(), SERVICE_EVENTS, GUI_TRUE);
 }
 
// This is an example of a repeating button.
buttonDelete = New_Object ( BUTTON );
Set_Property ( buttonDelete, DRAW_GRAPHIC, (long) graphicDelete);
Set_Property ( buttonDelete, PRESS_GRAPHIC, (long) graphicPress );
Set_Property ( buttonDelete, RELEASE_GRAPHIC, (long) graphicDelete);
Set_Property ( buttonDelete, BLOCK_ON_PRESS, GUI_TRUE );
Set_Property ( buttonDelete, BLOCK_ON_HOLD, GUI_TRUE );
Set_Property ( buttonDelete, BEEP_ON_HOLD, GUI_TRUE );
Set_Property ( buttonDelete, PRESS_EVENT_PROCEDURE,
 Delete_Event_Procedure_xaddr );
Set_Property ( buttonDelete, HELD_EVENT_PROCEDURE,
 Delete_Event_Procedure_xaddr );

: Delete_Event_Procedure ( -- )
 \ The Delete Button Event Procedure code would go here.
 
 \ Reset SERVICE_EVENTS to GUI_TRUE to re-enable event servicing.
 \ This must be the last thing done by the event procedure.
 GUI_TOOLKIT SERVICE_EVENTS GUI_TRUE Set_Property
 ;
 
\ This is an example of a repeating button.
BUTTON new_object buttonDelete !
buttonDelete @ DRAW_GRAPHIC graphicDelete @ u>d Set_Property
buttonDelete @ PRESS_GRAPHIC graphicPress @ u>d Set_Property
buttonDelete @ RELEASE_GRAPHIC graphicDelete @ u>d Set_Property
buttonDelete @ BEEP_ON_HOLD GUI_TRUE Set_Property
buttonDelete @ BLOCK_ON_PRESS GUI_TRUE Set_Property
buttonDelete @ BLOCK_ON_HOLD GUI_TRUE Set_Property
buttonDelete @ PRESS_EVENT_PROCEDURE cfa.FOR Delete_Event_Procedure
 Set_Property
buttonDelete @ HELD_EVENT_PROCEDURE cfa.FOR Delete_Event_Procedure
 Set_Property

Libraries: library.c , library.4th

See also: BLOCK_ON_PRESS, BLOCK_ON_RELEASE, SERVICE_EVENTS

C: BLOCK_ON_PRESS
4th: BLOCK_ON_PRESS

Type: Constant
Return Value: Integer

The name of a button property that when set, disables the servicing touchscreen events until a RELEASE_EVENT occurs and the GUI_TOOLKIT() property SERVICE_EVENTS is set to GUI_TRUE. Set this button property for repeating buttons and buttons that change screens. The final line of the hold event procedure must re-enable the servicing of events by setting the GUI_TOOLKIT() property SERVICE_EVENTS to GUI_TRUE.

extern xaddr Delete_Event_Procedure_xaddr ( void );
void Delete_Event_Procedure ( void )
 {
 // The Delete Button Event Procedure code would go here.
 
 // Reset SERVICE_EVENTS to GUI_TRUE to re-enable event servicing.
 // This must be the last thing done by the event procedure.
 Set_Property( GUI_TOOLKIT(), SERVICE_EVENTS, GUI_TRUE);
 }
 
// This is an example of a repeating button.
buttonDelete = New_Object ( BUTTON );
Set_Property ( buttonDelete, DRAW_GRAPHIC, (long) graphicDelete);
Set_Property ( buttonDelete, PRESS_GRAPHIC, (long) graphicPress );
Set_Property ( buttonDelete, RELEASE_GRAPHIC, (long) graphicDelete);
Set_Property ( buttonDelete, BLOCK_ON_PRESS, GUI_TRUE );
Set_Property ( buttonDelete, BLOCK_ON_HOLD, GUI_TRUE );
Set_Property ( buttonDelete, BEEP_ON_HOLD, GUI_TRUE );
Set_Property ( buttonDelete, PRESS_EVENT_PROCEDURE,
 Delete_Event_Procedure_xaddr );
Set_Property ( buttonDelete, HELD_EVENT_PROCEDURE,
 Delete_Event_Procedure_xaddr );

: Delete_Event_Procedure ( -- )
 \ The Delete Button Event Procedure code would go here.
 
 \ Reset SERVICE_EVENTS to GUI_TRUE to re-enable event servicing.
 \ This must be the last thing done by the event procedure.
 GUI_TOOLKIT SERVICE_EVENTS GUI_TRUE Set_Property
 ;
 
\ This is an example of a repeating button.
BUTTON new_object buttonDelete !
buttonDelete @ DRAW_GRAPHIC graphicDelete @ u>d Set_Property
buttonDelete @ PRESS_GRAPHIC graphicPress @ u>d Set_Property
buttonDelete @ RELEASE_GRAPHIC graphicDelete @ u>d Set_Property
buttonDelete @ BEEP_ON_HOLD GUI_TRUE Set_Property
buttonDelete @ BLOCK_ON_PRESS GUI_TRUE Set_Property
buttonDelete @ BLOCK_ON_HOLD GUI_TRUE Set_Property
buttonDelete @ PRESS_EVENT_PROCEDURE cfa.FOR Delete_Event_Procedure
 Set_Property
buttonDelete @ HELD_EVENT_PROCEDURE cfa.FOR Delete_Event_Procedure
 Set_Property

Libraries: library.c , library.4th

See also: BLOCK_ON_HOLD, BLOCK_ON_RELEASE, SERVICE_EVENTS

C: BLOCK_ON_RELEASE
4th: BLOCK_ON_RELEASE

Type: Constant
Return Value: Integer

The name of a button property that when set, disables the servicing touchscreen events until a RELEASE_EVENT occurs and the GUI_TOOLKIT() property SERVICE_EVENTS is set to GUI_TRUE.

Set_Property ( buttonStop, BLOCK_ON_RELEASE, GUI_TRUE );

buttonStop @ BLOCK_ON_RELEASE GUI_TRUE Set_Property

Libraries: library.c , library.4th

See also: BLOCK_ON_HOLD, BLOCK_ON_PRESS, SERVICE_EVENTS

C: BLUE
4th: BLUE

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to blue if the default color palette is used.

Set_Property(textboxTitle, TEXTBOX_BACKGROUND, (long)BLUE);

TextboxTitle @ TEXTBOX_BACKGROUND BLUE u>d Set_Property

Libraries: library.c , library.4th

C: BMP_FORMAT
4th: BMP_FORMAT

Type: Constant
Return Value: Integer

A constant used to set the image file format used with the functions Graphic_To_Image, Screen_To_Image, and Simulated_Touch_To_Image. Currently, the bitmap format is the only supported image format.

Graphic_To_Image( graphicPump, xaddrBuffer, (long) 300, BMP_FORMAT);

GraphicPump @ xaddrBuffer x@ 300 u>d BMP_FORMAT Graphic_To_Image

Libraries: library.c , library.4th

C: BORDER
4th: BORDER

Type: Constant
Return Value: Integer

The name of a textbox or plot property that draws a one pixel border around the object. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. BOARDER is initialized to GUI_FALSE when a plot or a textbox is instantiated.

Set_Property(textboxMessage, BORDER, GUI_TRUE);

textboxMessage @ BORDER GUI_TRUE Set_Property

Libraries: library.c , library.4th

C: BROWN
4th: BROWN

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to brown if the default color palette is used.

Set_Property(GUI_PEN(), DRAW_COLOR, (long)BROWN);

GUI_PEN DRAW_COLOR BROWN u>d Set_Property

Libraries: library.c , library.4th

C: BUFFER_SIZE
4th: BUFFER_SIZE

Type: Constant
Return Value: Integer

The name of a plot property that contains the size of the plot's circular data buffer in bytes. The size of the buffer is limited by the amount of heap space of GUI Toolkit or 65,535, whatever is smaller. The size of the buffer must also be larger than or equal to the pixel width of the plot object. BUFFER_SIZE is initialized to 240 when a plot is instantiated. We recommend setting the BUFFER_SIZE to the same value as the WIDTH_IN_PIXELS of your plot.

Set_Property(plotVoltage, BUFFER_SIZE, (long) 300);

plotVoltage @ BUFFER_SIZE 300 u>d Set_Property

Libraries: library.c , library.4th

C: BUFFER_SIZE_OUT_OF_RANGE
4th: BUFFER_SIZE_OUT_OF_RANGE

Type: Constant
Return Value: Integer

The name of an error that indicates the size of a buffer for a plot object must be greater than or equal to the width of the plot in pixels.

Set_Property(plotVoltage, BUFFER_SIZE, (long) 200);
if((Read_Error()>>16) == BUFFER_SIZE_OUT_OF_RANGE)
{
 printf("Buffer size must be >= plot width in pixels.\n");
 Clear_Error();
}

plotVoltage @ BUFFER_SIZE 200 u>d Set_Property
Read_Error NIP BUFFER_SIZE_OUT_OF_RANGE =
IF
 CR ." Buffer size must be >= plot width in pixels."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: BUFFER_SIZE_TOO_SMALL
4th: BUFFER_SIZE_TOO_SMALL

Type: Constant
Return Value: Integer

The name of an error that indicates the size of the buffer passed to the functions Graphic_To_Image, Screen_To_Image, or Simulated_Touch_To_Image is too small to hold the image.

Screen_To_Image( xaddrBuffer, (long) 300, BMP_FORMAT);
if((Read_Error()>>16) == BUFFER_SIZE_TOO_SMALL)
{
 printf("Buffer size must be large enough to hold the image.\n");
 Clear_Error();
}

xaddrBuffer x@ 300 u>d BMP_FORMAT Screen_To_Image
Read_Error NIP BUFFER_SIZE_TOO_SMALL =
IF
 CR ." Buffer size must be large enough to hold the image."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: BUTTON
4th: BUTTON

Type: Constant
Return Value: Integer

The name of an object type used to create a new button object. Buttons are objects with an associated graphic or textbox that respond to a user's touch on the touchscreen. New button objects have their BEEP_ON_PRESS property set to GUI_TRUE. The active area of a button (that is the area that is sensitive to touchscreen presses) is defined by a button's PRESS_GRAPHIC or textbox. A button can not have both a press graphic and a textbox.

buttonStop = New_Object( BUTTON );

BUTTON New_Object buttonStop !

Libraries: library.c , library.4th

C: BLUTTON_REFRESH
4th: BUTTON_REFRESH

Type: Constant
Return Value: Integer

The name of a button property that when set, causes the button to be refreshed.

Set_Property ( buttonStop, BUTTON_REFRESH, GUI_TRUE );

buttonStop @ BUTTON_REFRESH GUI_TRUE Set_Property

Libraries: library.c , library.4th

C: BUTTON_TEXTBOX
4th: BUTTON_TEXTBOX

Type: Constant
Return Value: Integer

The name of a button property that contains the textbox object reference for the button. The upper left corner of button is the same as the upper left corner of the textbox. BUTTON_TEXTBOX is uninitialized when a button is instantiated. Textboxes in buttons are useful for creating dynamic buttons or keypads where the text in the button needs to change based on an external event. If a button has a textbox, it should not have a draw graphic; the textbox will set the active area of the button.

Set_Property(buttonStop, BUTTON_TEXTBOX, (long) textboxInfo);

buttonStop @ BUTTON_TEXTBOX textboxInfo @ u>d Set_Property

Libraries: library.c , library.4th

C: void Buzz ( void )
4th: Buzz ( -- )

Type: Function

A method that passes a message to the slave processor telling the slave to play a specified frequency on the piezo electric buzzer for a certain length of time as specified by the BEEP_TIME and BEEP_NOTE property of the buzzer object. The default beep time is 3 milliseconds and the default beep note is C7 or 2093 Hz or midi note number 96.

Buzz();

Buzz

Libraries: library.c , library.4th

See also: BEEP_NOTE, BEEP_TIME

C: BUZZER_ON
4th: BUZZER_ON

Type: Constant
Return Value: Integer

The name of a buzzer property used to control the buzzer. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. BUZZER_ON is initialized to GUI_FALSE by Initialize_GUI.

Set_Property(GUI_BUZZER(), BUZZER_ON, GUI_FALSE); // Turn buzzer off.

GUI_BUZZER BUZZER_ON GUI_FALSE Set_Property \ Turn buffer off.  

Libraries: library.c , library.4th

C: CAL_COORDS
4th: CAL_COORDS

Type: Constant
Return Value: Integer

The name of a read only touchscreen property that contains the coordinates of the last touchscreen event. The y-coordinate is located in the most significant 16 bits and the x-coordinate is located in the least significant 16 bits.

longCoords = Get_Property(GUI_TOUCHSCREEN(), CAL_COORDS);
x_coord = longCoords & 0xFFFF;
y_coord = longCoords >> 16;

GUI_TOUCHSCREEN CAL_COORDS Get_Property y_coord ! x_coord !

Libraries: library.c , library.4th

C: void Calibrate ( ulong point1, ulong point2, ulong point3 )
4th: Calibrate( ud1 \ ud2 \ ud3 -- | ud1 = point1, ud2 = point2, ud3 = point3 )

Type: Function

Input Parameters:

• point0 – A 32 bit number with the raw touchscreen readings from a press at point (34,19). The raw y value is located in the most significant 16 bits and the raw x value is located in the least significant 16 bits.
• point1 – A 32 bit number with the raw touchscreen readings from a press at point (290,123). The raw y value is located in the most significant 16 bits and the raw x value is located in the least significant 16 bits.
• point2 – A 32 bit number with the raw touchscreen readings from a press at point (162,219). The raw y value is located in the most significant 16 bits and the raw x value is located in the least significant 16 bits.

A method that passes a message to the slave processor telling the slave to calibrate the analog touchscreen using the raw touchscreen readings of three points. The raw touchscreen readings are obtained with the Get_Property method and the RAW_COORDS property. The points are chosen to avoid non-linearities (points that are not too close to the edge), minimize scaling errors (points that are not too close to each other), and yield non-redundant simultaneous equations. The raw touchscreen readings are turned into coefficients that are applied to raw touchscreen readings each time the touchscreen is pressed. The coefficients are stored into flash and an error occurs if the flash memory is write protected. Errors include: FLASH_NOT_PROGRAMMABLE.

longPoint1 = Get_Property( GUI_TOUCHSCREEN(), RAW_COORDS);
Calibrate( longPoint1, longPoint2, longPoint3 );

GUI_TOUCHSCREEN RAW_COORDS Get_Property point1 2!
point1 2@ point2 2@ point3 2@ Calibrate

Libraries: library.c , library.4th

C: void Clear( int object_reference )
4th: Clear( n -- | n = object reference )

Type: Function

Input Parameters:

• object_reference – A 16 bit number that refers to a textbox, plot, or screen object.

A method that passes a message to the slave processor telling the slave to clear all data in the specified textbox, plot, or screen. If the object is a textbox, writes ASCII space to all positions in the textbox and sets the refresh flag to true so the textbox will be re-rendered the next time Refresh is called. If the object is a plot, sets each cell of the plot buffer to zero and sets the refresh flag to true. so the plot will be re-rendered the next time Refresh is called If the object is a screen, erases and unloads all objects in the screen. Refresh does not have to be called after clearing a screen. Errors include: INVALID_OBJECT.

Clear( GUI_SCREEN() );

GUI_SCREEN Clear

Libraries: library.c , library.4th

C: void Clear_Error ( void )
4th: Clear_Error ( -- )

Type: Function

A method that passes a message to the slave processor telling the slave to set the last reported error to NO_ERROR. Clear_Error should be called after Read_Error to prevent servicing the same error more than once.

Clear_Error();

Clear_Error

Libraries: library.c , library.4th

C: COLOR_STN
4th: COLOR_STN

Type: Constant
Return Value: Integer

A constant used to set the display type to color STN. Be sure to use the correct display type; otherwise the display may be damaged. With a colr STN display, the bit depth passed to the Initialize_GUI can be 1, 4 or 8. STN displays offer a lower cost alternative to the more expensive TFT displays. Errors include: INVALID_DISPLAY_TYPE.

Initialize_GUI(COLOR_STN, 4);

COLOR_STN 4 Initialize_GUI

Libraries: library.c , library.4th

See also: COLOR_TFT, MONO_STN

C: COLOR_TFT
4th: COLOR_TFT

Type: Constant
Return Value: Integer

A constant used to set the display type to color TFT. Be sure to use the correct display type; otherwise the display may be damaged. With a color TFT display, the bit depth passed to the Initialize_GUI can be 1, 4, or 8. TFT displays have higher contrast, brightness and viewing angles compared to STN displays. Errors include: INVALID_DISPLAY_TYPE.

Initialize_GUI(COLOR_TFT, 4);

COLOR_TFT 4 Initialize_GUI

Libraries: library.c , library.4th

See also: COLOR_STN, MONO_STN

C: COMMUNICATIONS_TIMEOUT
4th: COMMUNICATIONS_TIMEOUT

Type: Constant
Return Value: Integer

The name of a GUI Toolkit property that sets the length of time before a communications timeout error occurs. The units for this property is in milliseconds. This property is initialized to 5 seconds (5000 milliseconds) when the GUI Toolkit is initialized. This property should never be altered.

longTime = Get_Property(GUI_TOOLKIT(), COMMUNICATIONS_TIMEOUT);

GUI_TOOLKIT COMMUNICATIONS_TIMEOUT Get_Property longTime 2!

Libraries: library.c , library.4th

C: CONTRAST
4th: CONTRAST

Type: Constant
Return Value: Integer

The name of a display property that changes the contrast of the display. Valid values are 0 to 124. Values less than 0 and greater than 124 saturate at 0 and 124 respectively and have no additional effect on the contrast. The initial value of the contrast after Initialize_GUI is called is 62. For larger contrast adjustments use the hardware potentiometer. The contrast of an STN display will vary depending on the ambient temperature. This property allows the user to adjust the contrast using a button on the screen. This property has no effect for the TFT display.

Set_Property(GUI_DISPLAY(), CONTRAST, (long) 10);

GUI_DISPLAY CONTRAST 10 u>d Set_Property

Libraries: library.c , library.4th

C: void Copy_Screen( int source_screen, int destination_screen)
4th: Copy_Screen( n1 \ n2 -- | n1 = source screen, n2 = destination screen)

Type: Function

Input Parameters:

• source screen – A 16 bit reference to a screen object that is to be copied from.
• destination screen – A 16 bit reference to a screen object that is to be copied to.

A method that passes a message to the slave processor telling the slave to copy all of the objects and all of their properties from one screen into another screen. The source and destination screens can either be a screen (whose rendered objects reside in RAM outside of the display controller) or a display screen (whose rendered objects reside in RAM inside of the display controller). Errors include INVALID_SCREEN.

Copy_Screen(screenKeypad, GUI_SCREEN());

ScreenKeypad @ GUI_SCREEN Copy_Screen

Libraries: library.c , library.4th

C: CYAN
4th: CYAN

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to cyan if the default color palette is used.

Set_Property(GUI_FONT(), FONT_COLOR, (long)CYAN);

GUI_FONT FONT_COLOR CYAN u>d Set_Property

Libraries: library.c , library.4th

C: DAC_COUNT_CH0
4th: DAC_COUNT_CH0

Type: Constant
Return Value: Integer

The name of a GUI_PWM_DAC() property that is used to set the digital to analog converter (DAC) on pin 1 of the PWM / DAC Header, H15. Valid values from 0 to 65535 correspond to output voltages of 0.0 to 10.0 V respectively with 10 mA drive capability. Values from 0 through 256 are mapped to 0.0 volts, while greater values are scaled to the 0.0 - 10.0V range with a relative resolution of one part in 256. That is, the resolution is 1/256 of the output value. The DAC voltage is generated using a pulse width modulated (PWM) signal from PWM_0 (pin 2 on the PWM / DAC Header, H15) filtered with a low pass filter with a time constant of 10 milliseconds and passed through an op-amp in a voltage follower configuration.

Set_Property(GUI_PWM_DAC(), DAC_COUNT_CH0, (long)1000);

GUI_PWM_DAC DAC_COUNT_CH0 1000 u>d Set_Property

Libraries: library.c , library.4th

C: DAC_COUNT_CH1
4th: DAC_COUNT_CH1

Type: Constant
Return Value: Integer

The name of a GUI_PWM_DAC() property that is used to set the digital to analog converter (DAC) on pin 3 of the PWM / DAC Header, H15. Valid values from 0 to 65535 correspond to output voltages of 0.0 to 10.0 V respectively with 10 mA drive capability. Values from 0 through 256 are mapped to 0.0 volts, while greater values are scaled to the 0.0 - 10.0V range with a relative resolution of one part in 256. That is, the resolution is 1/256 of the output value. The DAC voltage is generated using a pulse width modulated (PWM) signal from PWM_1 (pin 4 on the PWM / DAC Header, H15) filtered with a low pass filter with a time constant of 10 milliseconds and passed through an op-amp in a voltage follower configuration.

Set_Property(GUI_PWM_DAC(), DAC_COUNT_CH1, (long)1000);

GUI_PWM_DAC DAC_COUNT_CH1 1000 u>d Set_Property

Libraries: library.c , library.4th

C: DAC_COUNT_CH2
4th: DAC_COUNT_CH2

Type: Constant
Return Value: Integer

The name of a GUI_PWM_DAC() property that is used to set the digital to analog converter (DAC) on pin 5 of the PWM / DAC Header, H15. Valid values from 0 to 65535 correspond to output voltages of 0.0 to 10.0 V respectively with 10 mA drive capability. Values from 0 through 256 are mapped to 0.0 volts, while greater values are scaled to the 0.0 - 10.0V range with a relative resolution of one part in 256. That is, the resolution is 1/256 of the output value. The DAC voltage is generated using a pulse width modulated (PWM) signal from PWM_0 (pin 6 on the PWM / DAC Header, H15) filtered with a low pass filter with a time constant of 10 milliseconds and passed through an op-amp in a voltage follower configuration.

Set_Property(GUI_PWM_DAC(), DAC_COUNT_CH2, (long)1000);

GUI_PWM_DAC DAC_COUNT_CH2 1000 u>d Set_Property

Libraries: library.c , library.4th

C: DAC_COUNT_CH3
4th: DAC_COUNT_CH3

Type: Constant
Return Value: Integer

The name of a GUI_PWM_DAC() property that is used to set the digital to analog converter (DAC) on pin 7 of the PWM / DAC Header, H15. Valid values from 0 to 65535 correspond to output voltages of 0.0 to 5.0 V respectively, with a 10KΩ output impedance. Values from 0 through 256 are mapped to 0.0 volts, while greater values are scaled to the 0.0 - 5.0V range with a relative resolution of one part in 256. That is, the resolution is 1/256 of the output value. The DAC voltage is generated using a pulse width modulated (PWM) signal from PWM_3 (pin 8 on the PWM / DAC Header, H15) filtered with a low pass filter with a time constant of 10 milliseconds.

Unlike PWM DAC channels 0, 1, and 2, which are opamp buffered, this channel is unbuffered. Consequently it is useful only as a reference voltage that can source a few microamps of current. Also, unlike the other channels, its output voltage range is 0.0 to 5.0 V rather than 0.0 to 10.0 V.

Set_Property(GUI_PWM_DAC(), DAC_COUNT_CH3, (long)1000);

GUI_PWM_DAC DAC_COUNT_CH3 1000 u>d Set_Property

Libraries: library.c , library.4th

C: DARK_GREY
4th: DARK_GREY

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to dark grey if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)DARK_GREY);

GUI_SCREEN SCREEN_BACKGROUND DARK_GREY u>d Set_Property

Libraries: library.c , library.4th

C: DATA_OUT_OF_RANGE
4th: DATA_OUT_OF_RANGE

Type: Constant
Return Value: Integer

The name of an error that indicates the data value added to a plot object is out of range. The valid data range of a plot is from 0 to the height of the plot object in pixels. If this error occurs, the Add_Data method recovers from the error by storing a value equal to the height of the plot object in pixels.

Add_Data(plotVoltage, 300);
if (Read_Error() == DATA_OUT_OF_RANGE)
{
 printf("Data value is out of range of the plot.\n");
 Clear_Error();
}

plotVoltage @ 300 Add_Data
Read_Error DATA_OUT_OF_RANGE =
IF
 CR ." Data value is out of range of the plot."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: DEFAULT_FONT
4th: DEFAULT_FONT

Type: Constant
Return Value: Integer

The name of a GUI Toolkit property that changes the default font used by subsequently created textboxes. The DEFAULT_FONT is set to the GUI_FONT() (which is a custom 10 pixel tall proportional font) when the GUI Toolkit is initialized.

int fontTimes;
fontTimes = New_Object( FONT );
Set_Property( fontTimes, IMAGE, TIMES_BMP);
Set_Property( fontTimes, FONT_WIDTH_DATA, TIMES_DAT);
Set_Property(GUI_TOOLKIT(), DEFAULT_FONT, (long)fontTimes);

VARIABLE fontTimes
FONT New_Object fontTimes !
fontTimes IMAGE TIMES_BMP Set_Property
fontTimes FONT_WIDTH_DATA TIMES_DAT Set_Property
GUI_TOOLKIT DEFAULT_FONT fontTimes @ u>d Set_Property

Libraries: library.c , library.4th

C: DEFAULT_PALETTE
4th: DEFAULT_PALETTE

Type: Constant
Return Value: Integer

The name of a GUI Toolkit property that changes the default palette. The DEFAULT_PALETTE is set to the GUI_PALETTE() (a custom defined palette of which the first 16 colors are shown at the beginning of this glossary) when the GUI Toolkit is initialized. The palette, also known as the color table or look up table (LUT), is used to define the colors that are viewable on the display from the many different possible combinations of red, green, and blue. The color STN and color TFT displays are capable of showing 4096 colors (4 bits for red, green and blue) but even when using the highest bit depth of 8 bits per pixel, only 256 colors are available at any time. When converting color images using the Image Conversion Program, the palette (LUT) is extracted from the image, stored in the data file, and named in the header file with the image name plus "_LUT". To load a custom pallete see the example code below. Changing the palette will effect all of the color images loaded on every screen.

int paletteCustom;
paletteCustom = New_Object( PALETTE );
Set_Property( paletteCustom, PALETTE_DATA, IMAGE_NAME_LUT);
Set_Property(GUI_TOOLKIT(), DEFAULT_PALETTE, (long)paletteCustom);

VARIABLE paletteCustom
PALETTE New_Object paletteCustom !
paletteCustom PALETTE_DATA IMAGE_NAME_LUT Set_Property
GUI_TOOLKIT DEFAULT_PALETTE paletteCustom @ u>d Set_Property

Libraries: library.c , library.4th

C: void Delete_Character( int textbox_reference )
4th: Delete_Character ( n -- | n = textbox_reference )

Type: Function

Input Parameters:

• textbox_reference – A 16 bit reference to a textbox object.

A method that passes a message to the slave processor telling the slave to delete a character from a textbox. The character is removed from the end of the string in the textbox. If there is no string in the textbox, this function does nothing. The textbox is re-rendered with the character removed only if the RENDER property of the textbox is set. Refresh or Redraw must be called on the screen containing the textbox after character is removed to display the changed textbox. Possible errors include: INVALID_TEXTBOX.

Delete_Character( textboxTitle ); 

textboxTitle @ Delete_Character 

Libraries: library.c , library.4th

See also: Add_Character

C: DIM_DISPLAY
4th: DIM_DISPLAY

Type: Constant
Return Value: Integer

The name of a display property that changes the brightness of the backlight. Valid values are 0 to 124. Values less than 0 and greater than 124 saturate at 0 and 124 respectively and have no additional effect on the backlight. The initial value of the property after Initialize_GUI is called is 120. This property allows the user to dim the backlight using a button on the screen.

Set_Property(GUI_DISPLAY(), DIM_DISPLAY, (long) 30);

GUI_DISPLAY DIM_DISPLAY 30 u>d Set_Property

Libraries: library.c , library.4th

C: DISPLAY_INITIALIZATION_FAILURE
4th: DISPLAY_INITIALIZATION_FAILURE

Type: Constant
Return Value: Integer

The name of an error that indicates there was an error initializing the display controller. This error indicates there was a hardware failure. Please contact Mosaic Industries for a Return Material Authorization.

Initialize_GUI(COLOR_STN, 4);
if ((Read_Error()>>16) == DISPLAY_INITIALIZATION_FAILURE)
{
 printf("Display initialization failure.\n");
 Clear_Error();
}

COLOR_STN 4 Initialize_GUI
Read_Error NIP DISPLAY_INITIALIZATION_FAILURE =
IF
 CR ." Display initialization failure."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: DISPLAY_SCREEN
4th: DISPLAY_SCREEN

Type: Constant
Return Value: Integer

The name of an object type used to create a new screen object whose data area resides in the display controller's RAM. Screens and display screens are objects that contain a collection of other functionally related objects such as graphics, buttons, textboxes, or plots. Only display screens can be made visible by setting the display screen's VISIBLE property to GUI_TRUE. GUI_SCREEN() is the visible display screen when the GUI Toolkit is initialized. When a screen is visible, its objects (graphics, buttons, textboxes, and plots) are shown on the display. Display screens are useful for quickly changing the visible screen without having to copy the screen from outside of the display controller's RAM. However, if GUI Toolkit is initialized to have a bit depth of 8 bits per pixel, then there is no additional space in the display controller's RAM for a display screen (the GUI_SCREEN() uses all of the display controller's RAM). If the GUI Toolkit is initialized to have a bit depth of 4 bits per pixel, then there is only space for one additional display screen besides the GUI_SCREEN().

screenMain = New_Object( DISPLAY_SCREEN );

DISPLAY_SCREEN New_Object screenMain !

Libraries: library.c , library.4th

C: DISPLAY_TYPE
4th: DISPLAY_TYPE

Type: Constant
Return Value: Integer

The name of a read only display property that returns the type of display set when the GUI Toolkit was initialzied. The display type is set by passing COLOR_STN, COLOR_TFT, or MONO_STN to Initialize_GUI. Be sure the display type matches the physical display or damage to the controller may occur.

longType = Get_Property(GUI_DISPLAY(), DISPLAY_TYPE);

GUI_DISPLAY DISPLAY_TYPE Get_Property longType 2!

Libraries: library.c , library.4th

See also: COLOR_STN, COLOR_TFT, MONO_STN

C: void Draw ( int x_coordinate, int y_coordinate )
4th: Draw ( n1 \ n2 -- | n1 = x coordinate, n2 = y coordinate )

Type: Function

Input Parameters:

• x-coordinate – A 16 bit number that specifies the x-coordinate of the point to draw.
• y-coordinate – A 16 bit number that specifies the y-coordinate of the point to draw.

A method that passes a message to the slave processor telling the slave to draw a point or line onto a screen. The screen to draw to, the type of object to draw (point or line), and the option to draw or erase, a point or a line are properties of the GUI_PEN(). To draw a line, set the LAST_COORDS property of the GUI_PEN() as the first end point and use the coordinates passed to Draw as the second end point. Errors include: X_OUT_OF_RANGE and Y_OUT_OF_RANGE.

Draw(45, 63);

45 63 Draw

Libraries: library.c , library.4th

C: DRAW_COLOR
4th: DRAW_COLOR

Type: Constant
Return Value: Integer

The name of a GUI_PEN() property that sets the color of the next line or pixel that is drawn with the Draw function. The DRAW_COLOR of the GUI_PEN() is initialized to WHITE when the GUI Toolkit is initialized.

Set_Property(GUI_PEN(), DRAW_COLOR, (long) BLUE );

GUI_PEN DRAW_COLOR BLUE u>d Set_Property

Libraries: library.c , library.4th

C: DRAW_GRAPHIC
4th: DRAW_GRAPHIC

Type: Constant
Return Value: Integer

The name of a button property that contains a reference to a graphic object that is drawn on a screen when the button is loaded. The DRAW_GRAPHIC sets the active area of a button. DRAW_GRAPHIC is uninitialized when a button is instantiated.

Set_Property(buttonStop, DRAW_GRAPHIC, (long) graphicStop);

buttonStop @ DRAW_GRAPHIC graphicStop @ u>d Set_Property

Libraries: library.c , library.4th

See also: PRESS_GRAPHIC, RELEASE_GRAPHIC

C: FIRST_VISIBLE_LINE
4th: FIRST_VISIBLE_LINE

Type: Constant
Return Value: Integer

The name of a textbox property that sets the top most line of a string that is rendered in a textbox. This property is used to scroll long strings that can't be completely shown in a textbox's area. For textbox's whose strings are completely shown in the textbox's area, this property does nothing. The FIRST_VISIBLE_LINE property is initialized to 0 when the textbox is instantiated. Setting this property to a value larger than the number of lines in the textbox will set FIRST_VISIBLE_LINE to the maximum valid value and display the last line. Setting this property to a value less than 0 will set FIRST_VISIBLE_LINE to 0 and display the first line.

void Scroll_Up_Event_Procedure ( void )
{
 long line;
 
 line = Get_Property ( textboxString, FIRST_VISIBLE_LINE);
 if ( line > 0 )
 {
   Set_Property ( textboxString, FIRST_VISIBLE_LINE, line - 1 );
   Refresh( GUI_SCREEN() ); // Be sure to refresh screen, show change.
 }
 
 // Re-enable the servicing of events.  The key was set to disable
 // events on press.
 Set_Property( GUI_TOOLKIT(), SERVICE_EVENTS, GUI_TRUE );
}
void Scroll_Down_Event_Procedure ( void )
{
 long line;
 
 line = Get_Property ( textboxString, FIRST_VISIBLE_LINE);
 
 Set_Property ( textboxString, FIRST_VISIBLE_LINE, line + 1 );
 Refresh( GUI_SCREEN() ); // Be sure to refresh screen, show change.
 
 // Re-enable the servicing of events.  The key was set to disable
 // events on press.
 Set_Property( GUI_TOOLKIT(), SERVICE_EVENTS, GUI_TRUE );
}

: Scroll_Up_Event_Procedure ( -- )
locals{ | &line }
 textboxString @ FIRST_VISIBLE_LINE Get_Property d>s DUP TO &line
 0> \ Make sure we don't go past 0
 IF
   textboxString @ FIRST_VISIBLE_LINE &line 1- u>d Set_Property
   GUI_SCREEN Refresh \ Be sure to refresh screen, show change.
 ENDIF
 \ Re-enable the servicing of events.  The key was set to disable
 \ events on press.
 GUI_TOOLKIT SERVICE_EVENTS GUI_TRUE Set_Property
;
: Scroll_Down_Event_Procedure ( -- )
locals{ | &line }
 textboxString @ FIRST_VISIBLE_LINE Get_Property d>s TO &line
 
 textboxString @ FIRST_VISIBLE_LINE &line 1+ u>d Set_Property
 GUI_SCREEN Refresh \ Be sure to refresh screen, show change.
 
 \ Re-enable the servicing of events.  The key was set to disable
 \ events on press.
 GUI_TOOLKIT SERVICE_EVENTS GUI_TRUE Set_Property
;

Libraries: library.c , library.4th

C: FLASH_NOT_PROGRAMMABLE
4th: FLASH_NOT_PROGRAMMABLE

Type: Constant
Return Value: Integer

The name of an error that indicates there was an error writing the calibration values into flash memory. Be sure the flash is not write-protected when Calibrate is called.

Calibrate( longPoint1, longPoint2, longPoint3);
if (Read_Error() == FLASH_NOT_PROGRAMMABLE)
{
 printf("Can't calibrate touchscreen; flash is write-protected.\n");
 Clear_Error();
}

point1 2@ point2 2@ point3 2@ Calibrate
Read_Error FLASH_NOT_PROGRAMMABLE =
IF
 CR ." Can't calibrate touchscreen; flash is write-protected."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: FONT
4th: FONT

Type: Constant
Return Value: Integer

The name of an object type used to create a new font object. A font is a set of images representing characters from some particular character set in a particular size and typeface. Before the font is associated with a textbox, its IMAGE must be set using the Set_Property method.

fontTimes = New_Object( FONT );

FONT New_Object fontTimes !

Libraries: library.c , library.4th

C: FONT_COLOR
4th: FONT_COLOR

Type: Constant
Return Value: Integer

The name of a button property that sets the color of the font used to render the string in the textbox. The FONT_COLOR is set to WHITE when a textbox is instantiated.

Set_Property(buttonStop, FONT_COLOR, (long) BLUE);

buttonStop @ FONT_COLOR BLUE u>d Set_Property

Libraries: library.c , library.4th

C: FONT_WIDTH_DATA
4th: FONT_WIDTH_DATA

Type: Constant
Return Value: Integer

The name of a font property that sets the address of an array that contains the width in pixels of each character of the font. Both the IMAGE and FONT_WIDTH_DATA properties of a font must be set before the font can be used to render text in a textbox. The Image Conversion Program allows Windows System and Printer fonts to be used with the GUI Toolkit. The Image Conversion Program stores the font image and width data and their addresses into the Image Data File and Image Header File respectively. The FONT_WIDTH_DATA is uninitialized when a font is instantiated.

Set_Property(fontTimes, IMAGE, TIMES_BMP);
Set_Property(fontTimes, FONT_WIDTH_DATA, TIMES_DAT);

fontTimes @ IMAGE TIMES_BMP Set_Property
fontTimes @ FONT_WIDTH_DATA TIMES_DAT Set_Property

Libraries: library.c , library.4th

C: ulong Get_Property ( int object_reference, int property )
4th: Get_Property( n1 \ n2 – ud | n1 = object reference, n2 = property, ud = value )

Type: Function

Input Parameters:

• object_reference – A 16 bit number that refers to the object whose property is to be read.
• property – A 16 bit number that specifies the property to get.

Return Value: An unsigned 32 bit number that contains the value of the property. All property values are 32 bits.

Get_Property is a method that passes a message to the slave processor telling it to return the value of a property of an object. Errors include: INVALID_OBJECT and INVALID_PROPERTY.

longHeight = Get_Property(GUI_DISPLAY(), HEIGHT_IN_PIXELS);

GUI_DISPLAY HEIGHT_IN_PIXELS Get_Property height 2!

Libraries: library.c , library.4th

See also: Set_Property

C: GRAPHIC
4th: GRAPHIC

Type: Constant
Return Value: Integer

The name of an object type used to create new graphic objects. A graphic is an object that contains a single image as a property. Before a graphic is loaded into a screen or associated with a button, its IMAGE must be set using the Set_Property method.

graphicStop = New_Object ( GRAPHIC );

GRAPHIC New_Object graphicStop !

Libraries: library.c , library.4th

C: int Graphic_To_Image ( int graphic_reference, xaddr buffer, long buffer_size, int format )
4th: Graphic_To_Image( n1 \ xaddr \ d \ n2 – n3 | n1 = graphic reference, xaddr = buffer, d = buffer size, n2 = format, n3 = error )

Type: Function

Input Parameters:

• graphic_reference – A 16 bit number that refers to the graphic object whose image will be written into the buffer.
• buffer – The extended address (xaddr) of the buffer in RAM that the image will be written into.
• buffer_size – A 32 bit number that specifies the size of the buffer in bytes.
• format – A 16 bit integer that specifies the format of the image. For now, only the BMP_FORMAT is allowed.

Return Value: A 16 bit number containing the error return value.

A method that passes a message to the slave processor telling the slave to convert the graphic object into an image and send it to the specified buffer xaddr in RAM on the master. The number of bytes stored into the buffer is limited to the specified buffer_size parameter. The first 4 bytes stored in the buffer contain a 32-bit byte count, followed by the image data in the specified format. Currently, the only valid format is the BMP_FORMAT, corresponding to the bitmap format This function returns the following error codes: NO_ERROR, INVALID_IMAGE_FORMAT, BUFFER_SIZE_TOO_SMALL, and INVALID_GRAPHIC .

switch(Graphic_To_Image(graphicStop,my_buffer,buffer_size,BMP_FORMAT))
{
 case NO_ERROR:              printf("No error.\n");                 break;
 case INVALID_IMAGE_FORMAT:  printf("Invalid format.\n");           break;
 case BUFFER_SIZE_TOO_SMALL: printf("Buffer size is too small.\n"); break;
 case INVALID_GRAPHIC:       printf("Invalid graphic.\n");          break;
}

graphicStop @ my_buffer x@ buffer_size 2@ BMP_FORMAT Graphic_To_Image
CASE
 NO_ERROR                 OF ." No error."                 CR ENDOF
 INVALID_IMAGE_FORMAT     OF ." Invalid image format."     CR ENDOF
 BUFFER_SIZE_IS_TOO_SMALL OF ." Buffer size is too small." CR ENDOF
 INVALID_GRAPHIC          OF ." Invalid graphic."          CR ENDOF
ENDCASE

Libraries: library.c , library.4th

See also: Screen_To_Image, Simulated_Touch_To_Image

C: GREEN
4th: GREEN

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to green if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)GREEN);

GUI_SCREEN SCREEN_BACKGROUND GREEN u>d Set_Property

Libraries: library.c , library.4th

C: GUI_BUZZER()
4th: GUI_BUZZER

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the buzzer of the GUI Toolkit. The buzzer is the hardware device that produces sound for audio feedback for button presses.

Set_Property(GUI_BUZZER(), BUZZER_ON, GUI_TRUE);

GUI_BUZZER BUZZER_ON GUI_TRUE Set_Property

Libraries: library.c , library.4th

C: GUI_ERROR()
4th: GUI_ERROR

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the error object of the GUI Toolkit. This low-level object is not accessed by the end user.

Libraries: library.c , library.4th

C: GUI_DISPLAY()
4th: GUI_DISPLAY

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the display of the GUI Toolkit. The display is the hardware device that produces a visual representation of information.

longHeight = Get_Property(GUI_DISPLAY(),HEIGHT_IN_PIXELS);

GUI_DISPLAY HEIGHT_IN_PIXELS Get_Property height 2!

Libraries: library.c , library.4th

C: GUI_FALSE
4th: GUI_FALSE

Type: Constant
Return Value: Long

A 32 bit constant equal to 0.

Set_Property(GUI_DISPLAY(), BACKLIGHT_ON, GUI_FALSE);

GUI_DISPLAY BACKLIGHT_ON GUI_FALSE Set_Property

Libraries: library.c , library.4th

See also: GUI_TRUE

C: GUI_FONT()
4th: GUI_FONT

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the default font of the GUI Toolkit. A font is a set of images representing characters from some particular character set in a particular size and typeface. When Initialize_GUI is called, the GUI Toolkit property DEFAULT_FONT is set to GUI_FONT() which is a custom proportional font that is 10 pixels tall. All of the characters of the font are shown at the beginning of the Glossary.

longHEIGHT = Get_Property(GUI_FONT(), HEIGHT_IN_PIXELS);

GUI_FONT HEIGHT_IN_PIXELS Get_Property fontHeight 2!

Libraries: library.c , library.4th

C: GUI_PALETTE()
4th: GUI_PALETTE

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the default palette of the GUI Toolkit. The DEFAULT_PALETTE is set to the GUI_PALETTE() (a custom defined palette of which the first 16 colors are shown at the beginning of this glossary) when the GUI Toolkit is initialized. The palette, also known as the color table or look up table (LUT), is used to define the colors that are viewable on the display from the many different possible combinations of red, green, and blue. The color STN and color TFT displays are capable of showing 4096 colors (4 bits for red, green and blue) but even when using the highest bit depth of 8 bits per pixel, only 256 colors are available at any time.

longData = Get_Property(GUI_PALETTE(), PALETTE_DATA);

GUI_PALETTE PALETTE_DATA Get_Property longData 2!

Libraries: library.c , library.4th

C: GUI_PEN()
4th: GUI_PEN

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the pen of the GUI Toolkit. The GUI_PEN() is used in conjunction with the Draw method to draw lines and geometrical figures onto screens.

Set_Property(GUI_PEN(), SHAPE, LINE);

GUI_PEN SHAPE LINE Set_Property

Libraries: library.c , library.4th

C: GUI_PWM_DAC()
4th: GUI_PWM_DAC

Type: Variable (Self-fetching)
Return Value: Integer

The name of the object used to access the pulse width modulated (PWM) and digital to analog (DAC) outputs located on the PWM / DAC Header. The PWM output requires a duty between 1 and 255 and a period between 2 to 255. The DAC output requires a value between 0 to 65535 corresponding to voltages of 0.0 to 10.0 V for PWM_DAC channels 0, 1, and 2, and 0.0 to 5.0 V for PWM_DAC channel 3. The DAC output is generated using its corresponding PWM channel filtered with a low pass filter with a time constant of 10 milliseconds and passed through an op-amp buffer (channels 0, 2, and 2) or left unbuffered (channel 3).

Set_Property(GUI_PWM_DAC(), DAC_COUNT_CH0, (long) 0xFF);

GUI_PWM_DAC DAC_COUNT_CH0 0xFF u>d Set_Property

Libraries: library.c , library.4th

See also: DAC_COUNT_CH0, PWM_DUTY_PERIOD_CH0

C: GUI_SCREEN()
4th: GUI_SCREEN

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the default display screen of the GUI Toolkit. Display screens are objects that contain a collection of other functionally related objects such as graphics, buttons, textboxes, or plots in the display controller's RAM. Only display screens can be made visible by setting the display screen's VISIBLE property to GUI_TRUE. GUI_SCREEN() is the visible display screen when the GUI Toolkit is initialized. When a screen is visible, its objects (graphics, buttons, textboxes, and plots) are shown on the display. Display screens are useful for quickly changing the visible screen without having to copy the screen from outside of the display controller's RAM. However, if GUI Toolkit is initialized to have a bit depth of 8 bits per pixel, then there is no additional space in the display controller's RAM for a display screen (the GUI_SCREEN() uses all of the display controller's RAM). If the GUI Toolkit is initialized to have a bit depth of 4 bits per pixel, then there is only space for one additional display screen besides the GUI_SCREEN().

Clear( GUI_SCREEN() );

GUI_SCREEN Clear

Libraries: library.c , library.4th

C: GUI_Show_All
4th: GUI_Show_All

Type: Function
Return Value: None.

A debugging routine that prints to the terminal the send and receive ring buffers, isr_control, message_length, and control lines. Used only for low level debugging.

GUI_Show_All( );

GUI_Show_All

Libraries: library.c , library.4th

C: GUI_TOOLKIT()
4th: GUI_TOOLKIT

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the GUI Toolkit. The GUI Toolkit object is the central object that contains properties relevant to all other objects.

Set_Property(GUI_TOOLKIT(), VERTICAL_SNAP_TO_GRID, GUI_TRUE);

GUI_TOOLKIT VERTICAL_SNAP_TO_GRID GUI_TRUE Set_Property

Libraries: library.c , library.4th

C: GUI_TOUCHSCREEN()
4th: GUI_TOUCHSCREEN

Type: Variable (Self-fetching)
Return Value: Integer

The name used to refer to the touchscreen of the GUI Toolkit.

longCoords = Get_Property(GUI_TOUCHSCREEN(), CAL_COORDS);

GUI_TOUCHSCREEN CAL_COORDS Get_Property coords 2!

Libraries: library.c , library.4th

C: GUI_TRUE
4th: GUI_TRUE

Type: Constant
Return Value: Long

A 32 bit constant equal to 0xFFFFFFFF.

Set_Property(GUI_TOOLKIT(), VERTICAL_SNAP_TO_GRID, GUI_TRUE);

GUI_TOOLKIT VERTICAL_SNAP_TO_GRID GUI_TRUE Set_Property

Libraries: library.c , library.4th

See also: GUI_FALSE

C: int Has_Screen_Changed ( void )
4th: Has_Screen_Changed ( -- u )

Type: Function
Return Value: A 16 bit number that contains the error return value.

A method that returns the value of the boolean flag that tells whether the screen image has been updated. This flag is set by Screen_Has_Changed and is cleared by Simulated_Touch_To_Image upon a successful image conversion. This flag is used by Simulated_Touch_To_Image to detect whether a time-consuming image conversion needs to be performed after the event procedure associated with a button press has executed. Most applications will not directly call this function, instead using the high level function Simulated_Touch_To_Image to implement the remote front panel feature with an Ether¬Smart Controller s.

if (Screen_Has_Changed())
{
 printf("Screen has changed.\n");
}
else
{
 printf("Screen has not changed.\n");
}

Screen_Has_Changed
IF
 ." Screen has changed." CR
ELSE
 ." Screen has not changed." CR
ENDIF

Libraries: library.c , library.4th

See also: Screen_Has_Changed, Simulated_Touch_To_Image

C: HEAP_FULL
4th: HEAP_FULL

Type: Constant
Return Value: Integer

The name of an error that indicates the heap of the GUI Toolkit is full. No new objects can be created and existing objects can not be resized.

graphicStop = New_Object( GRAPHIC );
if ((Read_Error()>>16) == HEAP_FULL)
{
 printf("Can't create new object, heap is full.\n");
 Clear_Error();
}

GRAPHIC New_Object graphicStop !
Read_Error NIP HEAP_FULL =
IF
 CR ." Can't create new object, heap is full"
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: HEIGHT_IN_PIXELS
4th: HEIGHT_IN_PIXELS

Type: Constant
Return Value: Integer

The name of a property that contains the height in pixels of a screen, button, textbox, graphic, or plot.

longHeight = Get_Property(GUI_DISPLAY(), HEIGHT_IN_PIXELS);

GUI_DISPLAY HEIGHT_IN_PIXELS Get_Property height 2!

Libraries: library.c , library.4th

See also: WIDTH_IN_PIXELS

C: HEIGHT_OUT_OF_RANGE
4th: HIGHT_OUT_OF_RANGE

Type: Constant
Return Value: Integer

The name of an error that indicates the height passed to Set_Property when changing the height of a plot, creates a plot taller than the screen. If the error occurs, Set_Property recovers from the error by setting the height of the plot equal to the height of the screen. An unchecked error occurs when a plot that is already loaded into a screen is resized beyond the height of the screen.

Set_Property(plotVoltage, HEIGHT_IN_PIXELS, (long) 500);
if ((Read_Error()>>16) == HEIGHT_OUT_OF_RANGE)
{
 printf("Height of the plot is greater than the height of screen.\n");
 Clear_Error();
}

plotVoltage @ HEIGHT_IN_PIXELS 500 u>d Set_Property
Read_Error NIP HEIGHT_OUT_OF_RANGE =
IF
 CR ." Height of the plot is greater than the height of the screen."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: HELD_EVENT
4th: HELD_EVENT

Type: Constant
Return Value: Long

The name of a value of the touchscreen property LAST_EVENT that indicates a user has touched the touchscreen and continues to hold it down.

if (Get_Property(GUI_TOUCHSCREEN(), LAST_EVENT)==HELD_EVENT)
{
 printf("Last touchscreen event was a held event.\n");
}

GUI_TOUCHSCREEN LAST_EVENT Get_Property HELD_EVENT d=
IF
 CR ." Last touchscreen event was a held event."
ENDIF

Libraries: library.c , library.4th

See also: PRESS_EVENT, RELEASE_EVENT, NO_EVENT

C: HELD_EVENT_PROCEDURE
4th: HELD_EVENT_PROCEDURE

Type: Constant
Return Value: Integer

The name of a button property that contains the xcfa of a user defined held event procedure. The held event procedure is called each time the button receives a held event. Held event procedures can not take or return any parameters, but they can modify variables. HELD_EVENT_PROCEDURE is uninitialized when a button is instantiated. This property is typically used for repeating buttons (buttons that repeat their action when the button is held down, like a delete button). To create a repeating button, the BLOCK_ON_PRESS and BLOCK_ON_HOLD button properties must be set and the HELD_EVENT_PROCEDURE must re-enable the servicing of events by setting the SERVICE_EVENTS property of the GUI_TOOLKIT().

extern void Delete_Event_Procedure ( void );
void Delete_Event_Procedure ( void )
 {
 // The Delete Button Event Procedure code would go here.
 
 // Reset SERVICE_EVENTS to GUI_TRUE to re-enable event servicing.
 // This must be the last thing done by the event procedure.
 Set_Property( GUI_TOOLKIT(), SERVICE_EVENTS, GUI_TRUE);
 }
 
// This is an example of a repeating button.
buttonDelete = New_Object ( BUTTON );
Set_Property ( buttonDelete, DRAW_GRAPHIC, (long) graphicDelete);
Set_Property ( buttonDelete, PRESS_GRAPHIC, (long) graphicPress );
Set_Property ( buttonDelete, RELEASE_GRAPHIC, (long) graphicDelete);
Set_Property ( buttonDelete, BLOCK_ON_PRESS, GUI_TRUE );
Set_Property ( buttonDelete, BLOCK_ON_HOLD, GUI_TRUE );
Set_Property ( buttonDelete, BEEP_ON_HOLD, GUI_TRUE );
Set_Property ( buttonDelete, PRESS_EVENT_PROCEDURE,
 delete_event_procedure );
Set_Property ( buttonDelete, HELD_EVENT_PROCEDURE,
 delete_event_procedure );

: Delete_Event_Procedure ( -- )
 \ The Delete Button Event Procedure code would go here.
 
 \ Reset SERVICE_EVENTS to GUI_TRUE to re-enable event servicing.
 \ This must be the last thing done by the event procedure.
 GUI_TOOLKIT SERVICE_EVENTS GUI_TRUE Set_Property
 ;
 
\ This is an example of a repeating button.
BUTTON new_object buttonDelete !
buttonDelete @ DRAW_GRAPHIC graphicDelete @ u>d Set_Property
buttonDelete @ PRESS_GRAPHIC graphicPress @ u>d Set_Property
buttonDelete @ RELEASE_GRAPHIC graphicDelete @ u>d Set_Property
buttonDelete @ BEEP_ON_HOLD GUI_TRUE Set_Property
buttonDelete @ BLOCK_ON_PRESS GUI_TRUE Set_Property
buttonDelete @ BLOCK_ON_HOLD GUI_TRUE Set_Property
buttonDelete @ PRESS_EVENT_PROCEDURE cfa.FOR Delete_Event_Procedure
 Set_Property
buttonDelete @ HELD_EVENT_PROCEDURE cfa.FOR Delete_Event_Procedure
 Set_Property

Libraries: library.c , library.4th

See also: PRESS_EVENT_PROCEDURE, RELEASE_EVENT_PROCEDURE

C: HORIZONTAL_SNAP_TO_GRID
4th: HORIZONTAL_SNAP_TO_GRID

Type: Constant
Return Value: Integer

The name of a property of the GUI_TOOLKIT() that aligns objects loaded onto a screen onto a horizontal grid. For speed purposes, this property can not be changed so all objects must be loaded onto a byte boundary. For a bit depth of 1 bit per pixel, the horizontal grid granularity is 8 pixels wide. For a bit depth of 4 bits per pixel, the horizontal grid granularity is 2 pixels wide. For a bit depth of 8 bits per pixel, the horizontal grid granularity is 1 pixel wide. The only possible value of this property is the boolean GUI_TRUE.

longFlag = Get_Property(GUI_TOOLKIT(), HORIZONTAL_SNAP_TO_GRID);

GUI_TOOLKIT HORIZONTAL_SNAP_TO_GRID Get_Property flag 2!

Libraries: library.c , library.4th

See also: VERTICAL_SNAP_TO_GRID

C: IMAGE
4th: IMAGE

Type: Constant
Return Value: Integer

The name of a property of a graphic or font object that contains the address of the image data. The address of the image data is generated by the Mosaic's Image Conversion Program and stored in the Image Header File as a constant.

Set_Property(graphicSTOP, IMAGE, STOP_BMP);

graphicStop @ IMAGE STOP_BMP Set_Property

Libraries: library.c , library.4th

C: IN_DISPLAY
4th: IN_DISPLAY

Type: Constant
Return Value: Integer

The name of a screen property that indicates the location of the screen's data buffer (where images are drawn into) is in the display controller. The GUI_SCREEN() and display screens have their data buffers located in the display controller. Screens have their data buffers located in the GUI Heap. This property is read only. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE.

longFlag = Get_Property(GUI_SCREEN(), IN_DISPLAY);

GUI_SCREEN IN_DISPLAY Get_Property flag 2!

Libraries: library.c , library.4th

C: void Initialize_GUI ( int display_type, int bit_depth )
4th: Initialize_GUI ( n1 \ n2 – | n1 = display type, n2 = bit depth )

Type: Function

Input Parameters:

• display_type – A 16 bit number that specifies the type of display. MONO_STN, COLOR_STN, and COLOR_TFT are the only valid display types.
• bit_depth – A 16 bit number that specifies the bit depth. 1, 4, and 8 are the only valid bit depths.

Initializes the GUI Toolkit by setting up the SPI channel and handshaking lines used to communicate with the slave processor and then sends a message to the slave processor telling it to initializing the display, touchscreen, and preinstantiated GUI objects. Be sure to use the correct display type; otherwise the display may be damaged. For monochrome STN displays, the only valid bit depth is 1 bit per pixel. Do not call any other GUI Toolkit method before calling Initialize_GUI. Errors include: DISPLAY_INITIALIZATION_FAILURE and TOUCHSCREEN_INITIALIZATION_FAILURE.

Initialize_GUI( COLOR_TFT, 4);

COLOR_TFT 4 Initialize_GUI

Libraries: library.c , library.4th

C: INVALID_BIT_DEPTH
4th: INVALID_BIT_DEPTH

Type: Constant
Return Value: Integer

The name of an error that indicates the bit depth passed to Initialize_GUI is not valid. Valid bit depths for the COLOR_STN and COLOR_TFT displays are 1, 4, and 8 while the valid bit depth for the MONO_STN display is 1.

Initialize_GUI( COLOR_STN, 5 );
if ((Read_Error()>>16) == INVALID_BIT_DEPTH)
{
 printf("Attempted to use an invalid bit depth.\n");
 Clear_Error();
}

COLOR_TFT 5 Initialize_GUI
Read_Error NIP INVALID_BIT_DEPTH =
IF
 CR ." Attempted to use an invalid bit depth."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_DISPLAY_TYPE
4th: INVALID_DISPLAY_TYPE

Type: Constant
Return Value: Integer

The name of an error that indicates the display type passed to Initialize_GUI is not valid. Valid display types are COLOR_STN, COLOR_TFT, and MONO_STN.

Initialize_GUI( BLUE, 4 );
if ((Read_Error()>>16) == INVALID_DISPLAY_TYPE)
{
 printf("Attempted to use an invalid display type.\n");
 Clear_Error();
}

BLUE 4 Initialize_GUI
Read_Error NIP INVALID_DISPLAY_TYPE =
IF
 CR ." Attempted to use an invalid display type."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_FONT
4th: INVALID_FONT

Type: Constant
Return Value: Integer

The name of an error that indicates the font object associated with a textbox or the GUI Toolkit is not valid.

Set_Property(textboxMesg, TEXTBOX_FONT, (long) graphicStop);
if ((Read_Error()>>16) == INVALID_FONT)
{
 printf("Attempted to use an invalid font for textboxMesg.\n");
 Clear_Error();
}

textboxMesg @ TEXTBOX_FONT graphicStop @ u>d Set_Property
Read_Error NIP INVALID_FONT =
IF
 CR ." Attempted to use an invalid font for textboxMesg."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_GRAPHIC
4th: INVALID_GRAPHIC

Type: Constant
Return Value: Integer

The name of an error that indicates the graphic object associated with a button is not valid.

Set_Property(buttonStop, PRESS_GRAPHIC, (long) fontLarge);
if ((Read_Error()>>16) == INVALID_GRAPHIC)
{
 printf("Attempted to use an invalid graphic in buttonStop.\n");
 Clear_Error();
}

buttonStop @ PRESS_GRAPHIC fontLarge @ u>d Set_Property
Read_Error NIP INVALID_GRAPHIC =
IF
 CR ." Attempted to use an invalid graphic in buttonStop."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_IMAGE
4th: INVALID_IMAGE

Type: Constant
Return Value: Integer

The name of an error that indicates the address of the image data is not valid.

Set_Property(graphicStop, IMAGE, GUI_FALSE);
if ((Read_Error()>>16) == INVALID_IMAGE)
{
 printf("Image for graphicStop is not valid.\n");
 Clear_Error();
}

graphicStop @ IMAGE GUI_FALSE Set_Property
Read_Error NIP INVALID_IMAGE =
IF
 CR ." Image for graphicStop is not valid."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_IMAGE_FORMAT
4th: INVALID_IMAGE_FORMAT

Type: Constant
Return Value: Integer

The name of an error that indicates the image format passed to Screen_To_Image, Graphic_To_Image, or Simulated_Touch_To_Image is invalid. For now, the only valid image format is BMP_FORMAT.

Screen_To_Image( buffer_xaddr, buffer_size, PCX_FORMAT );
if ((Read_Error()>>16) == INVALID_IMAGE_FORMAT)
{
 printf("The image format is not valid.\n");
 Clear_Error();
}

buffer_xaddr x@ buffer_size 2@ PCX_FORMAT Screen_To_Image
Read_Error NIP INVALID_IMAGE_FORMAT =
IF
 CR ." The image format is not valid."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_OBJECT
4th: INVALID_OBJECT

Type: Constant
Return Value: Integer

The name of an error that indicates the object reference is not valid.

Set_Property(invalidObj, IMAGE, STOP_BMP);
if ((Read_Error()>>16) == INVALID_OBJECT)
{
 printf("Attempted to set a property for an invalid object.\n");
 Clear_Error();
}

invalidObject @ IMAGE STOP_BMP Set_Property
Read_Error NIP INVALID_OBJECT =
IF
 CR ." Attempted to set a property for an invalid object."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_PALETTE
4th: INVALID_PALETTE

Type: Constant
Return Value: Integer

The name of an error that indicates the palette reference is not valid.

Set_Property(GUI_TOOLKIT(), DEFAULT_PALETTE, buttonStop);
if ((Read_Error()>>16) == INVALID_PALETTE)
{
 printf("Tried to set an invalid palette to the default palette.\n");
 Clear_Error();
}

GUI_TOOLKIT DEFAULT_PALETTE buttonStop @ u>d Set_Property
Read_Error NIP INVALID_PALETTE =
IF
 CR ." Attempted to set an invalid palette to the default palette."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_PEN_SHAPE
4th: INVALID_PEN_SHAPE

Type: Constant
Return Value: Integer

The name of an error that indicates the pen shape is not valid. Valid pen shapes are POINT and LINE.

Set_Property(GUI_PEN(), SHAPE, GUI_CIRCLE);
if ((Read_Error()>>16) == INVALID_PEN_SHAPE)
{
 printf("Attempted to set an invalid shape for the pen object.\n");
 Clear_Error();
}

GUI_PEN SHAPE GUI_CIRCLE Set_Property
Read_Error NIP INVALID_PEN_SHAPE =
IF
 CR ." Attempted to set an invalid shape for the pen object."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_PEN_TYPE
4th: INVALID_PEN_TYPE

Type: Constant
Return Value: Integer

The name of an error that indicates that the property returned by the pen type is not valid. Valid pen type properties are SET and UNSET.

Set_Property(GUI_PEN(), PEN_TYPE, DOTTED_LINE);
if ((Read_Error()>>16) == INVALID_PEN_TYPE)
{
 printf("Attempted to set an invalid type for the pen object.\n");
 Clear_Error();
}

GUI_PEN PEN_TYPE DOTTED_LINE Set_Property
Read_Error NIP INVALID_PEN_TYPE =
IF
 CR ." Attempted to set an invalid type for the pen object."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_PLOT
4th: INVALID_PLOT

Type: Constant
Return Value: Integer

The name of an error that indicates the plot object reference is not valid.

Add_Data(graphicStop, 14);
if ((Read_Error()>>16) == INVALID_PLOT)
{
 printf("Attempted to add data to an invalid plot object.\n");
 Clear_Error();
}

graphicStop @ 14 Add_Data
Read_Error NIP INVALID_PLOT =
IF
 CR ." Attempted to add data to an invalid plot object."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_PROPERTY
4th: INVALID_PROPERTY

Type: Constant
Return Value: Integer

The name of an error that indicates the property is not valid.

Set_Property(graphicStop, TEXTBOX_FONT, STOP_BMP);
if ((Read_Error()>>16) == INVALID_PROPERTY)
{
 printf("Attempted to set an invalid property for graphicStop.\n");
 Clear_Error();
}

graphicStop @ TEXTBOX_FONT STOP_BMP Set_Property
Read_Error NIP INVALID_PROPERTY =
IF
 CR ." Attempted to set an invalid property for graphicStop."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_SCREEN
4th: INVALID_SCREEN

Type: Constant
Return Value: Integer

The name of an error that indicates the screen object reference is not valid.

Load(invalidObj, graphicStop, 0, 0);
if ((Read_Error()>>16) == INVALID_SCREEN)
{
 printf("Attempted to load a graphic into an invalid screen.\n");
 Clear_Error();
}

invalidObj @ graphicStop @ 0 0 Load
Read_Error NIP INVALID_SCREEN =
IF
 CR ." Attempted to load a graphic into an invalid screen."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVALID_TEXTBOX
4th: INVALID_TEXTBOX

Type: Constant
Return Value: Integer

The name of an error that indicates the textbox object reference is not valid.

STRING_TO_TEXTBOX(invalidObj, "hello", 0, 0);
if ((Read_Error()>>16) == INVALID_TEXTBOX)
{
 printf("Attempted to write a string into an invalid textbox.\n");
 Clear_Error();
}

invalidObj @ " hello" 0 0 String_To_Textbox
Read_Error NIP INVALID_TEXTBOX =
IF
 CR ." Attempted to write a string into an invalid textbox."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: INVERT_DISPLAY
4th: INVERT_DISPLAY

Type: Constant
Return Value: Integer

The name of a display property that inverts all pixels on the display. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. INVERT_DISPLAY is set to GUI_FALSE by Initialize_GUI. Not recommended for bit depths other than 1.

Set_Property(GUI_DISPLAY(), INVERT_DISPLAY, GUI_TRUE);

GUI_DISPLAY INVERT_DISPLAY GUI_TRUE Set_Property

Libraries: library.c , library.4th

C: LAST_COORDS
4th: LAST_COORDS

Type: Constant
Return Value: Integer

The name of a pen property that contains the x and y-coordinates used with the previous call of Draw. The y-coordinate is located in the most significant 16 bits and the x-coordinate is located in the least significant 16 bits. The contents of this property are used as the first end point of a line drawn with the Draw method. The x and y coordinates passed to the Draw method supply the second end point for the line.

Set_Property(GUI_PEN(), LAST_COORDS, (long) ((y_coord<<16) | x_coord));

GUI_PEN LAST_COORDS x_coord @ y_coord @ Set_Property

Libraries: library.c , library.4th

C: LAST_EVENT
4th: LAST_EVENT

Type: Constant
Return Value: Integer

The name of a touchscreen property that contains the last touchscreen event. This property is read only. Possible values of this property are NO_EVENT, PRESS_EVENT, HELD_EVENT, and RELEASE_EVENT.

longEvent = Get_Property(GUI_TOUCHSCREEN(), LAST_EVENT);

GUI_TOUCHSCREEN LAST_EVENT Get_Property event 2!

Libraries: library.c , library.4th

See also: NO_EVENT, PRESS_EVENT, HELD_EVENT, RELEASE_EVENT

C: LIGHT_BLUE
4th: LIGHT_BLUE

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to light blue if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)LIGHT_BLUE);

GUI_SCREEN SCREEN_BACKGROUND LIGHT_BLUE u>d Set_Property

Libraries: library.c , library.4th

C: LIGHT_CYAN
4th: LIGHT_CYAN

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to light cyan if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)LIGHT_CYAN);

GUI_SCREEN SCREEN_BACKGROUND LIGHT_CYAN u>d Set_Property

Libraries: library.c , library.4th

C: LIGHT_GREEN
4th: LIGHT_GREEN

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to light green if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)LIGHT_GREEN);

GUI_SCREEN SCREEN_BACKGROUND LIGHT_GREEN u>d Set_Property

Libraries: library.c , library.4th

C: LIGHT_GREY
4th: LIGHT_GREY

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to light grey if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)LIGHT_GREY);

GUI_SCREEN SCREEN_BACKGROUND LIGHT_GREY u>d Set_Property

Libraries: library.c , library.4th

C: LIGHT_MAGENTA
4th: LIGHT_MAGENTA

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to light magenta if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)LIGHT_MAGENTA);

GUI_SCREEN SCREEN_BACKGROUND LIGHT_MAGENTA u>d Set_Property

Libraries: library.c , library.4th

C: LIGHT_RED
4th: LIGHT_RED

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to light red if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)LIGHT_RED);

GUI_SCREEN SCREEN_BACKGROUND LIGHT_RED u>d Set_Property

Libraries: library.c , library.4th

C: LINE
4th: LINE

Type: Constant
Return Value: Long

The name of a value of the SHAPE property of the GUI_PEN() object. When the SHAPE property of the GUI_PEN() object is set to LINE, the Draw method draws a line between the LAST_COORDS stored in the GUI_PEN() and the specified x and y parameters.

Set_Property(GUI_PEN(), SHAPE, LINE);

GUI_PEN SHAPE LINE Set_Property

Libraries: library.c , library.4th

See also: POINT

C: void Load ( int screen_reference, int object_reference, int x_coordinate, int y_coordinate )
4th: Load ( n1 \ n2 \ n3 \ n4 -- | n1 = screen reference, n2 = object reference, n3 = x coord, n4 = y coord )

Type: Function

Input Parameters:

• screen_reference – A 16 bit variable that refers to the screen that the object specified by object_reference will be loaded into.
• object_reference – A 16 bit variable that refers to an object to be loaded onto a screen.
• x_coordinate – A 16 bit number that specifies the location of the left edge of the object in the horizontal direction relative to the left edge of the screen. For speed, the x-coordinate must fall on a byte boundary (1 pixel boundary for a bit depth of 8 bits per pixel, a 2 pixel boundary for a bit depth of 4 bits per pixel, and an 8 pixel boundary for a bit depth of 1 bit per pixel). The valid range for the x-coordinate depends on the width of the object. The x-coordinate must be specified so that the entire object is between 0 and 319 pixels. The origin of a screen is it's upper left corner.
• y_coordinate – A 16 bit number that specifies the location of the top of the object in the vertical direction relative to the top edge of the screen. The valid range of the y-coordinate depends on the height of the object. The y-coordinate must be specified so that the entire object is between 0 and 239 pixels. The origin of a screen is it's upper left corner.

A method that passes a message to the slave processor telling the slave to load an object into a screen at a specified location and renders the image of the object into the screen. Errors include: HEAP_FULL, INVALID_SCREEN, INVALID_OBJECT, X_OUT_OF_RANGE, and Y_OUT_OF_RANGE.

Load( GUI_SCREEN(), buttonStop, 0, 0);

GUI_SCREEN buttonStop @ 0 0 Load

Libraries: library.c , library.4th

See also: Un_Load

C: MAGENTA
4th: MAGENTA

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to magenta if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)MAGENTA);

GUI_SCREEN SCREEN_BACKGROUND MAGENTA u>d Set_Property

Libraries: library.c , library.4th

C: MONO_STN
4th: MONO_STN

Type: Constant
Return Value: Integer

A constant used to set the display type to mono STN. Be sure to use the correct display type; otherwise the display may be damaged. With a monochrome STN display, the bit depth passed to the Initialize_GUI must be 1. Mono STN displays offer a lower cost alternative to the more expensive color displays. Errors include: INVALID_DISPLAY_TYPE.

Initialize_GUI(MONO_STN, 1);

MONO_STN 1 Initialize_GUI

Libraries: library.c , library.4th

See also: COLOR_TFT, MONO_STN

C: int New_Object ( int object_type )
4th: New_Object( n1 – n2 | n1 = object type, n2 = object reference )

Type: Function

Input Parameters:

• object_type – A 16 bit number that refers to an object type. Valid object types are GRAPHIC, FONT, TEXTBOX, PLOT, BUTTON, SCREEN, or DISPLAY_SCREEN

Return Value: An unsigned 16 bit number that refers to the newly created object. This number should be stored into an object reference variable which can later be used to set the properties of the object, get the properties of the object, load the object into a screen, or unload the object from a screen.

A method that passes a message to the slave processor telling the slave to create new object and return a reference to the newly created object. Errors include: HEAP_FULL and INVALID_OBJECT.

graphicStop = New_Object( GRAPHIC );

GRAPHIC New_Object graphicStop !

Libraries: library.c , library.4th

C: NO_ERROR
4th: NO_ERROR

Type: Constant
Return Value: Integer

The name of a constant that indicates there was no error.

Initialize_GUI(COLOR_TFT, 4);
if ((Read_Error()>>16) == NO_ERROR)
{
 printf("No error was found.\n");
}

COLOR_TFT 4 Initialize_GUI
Read_Error NIP NO_ERROR =
IF
 CR ." No error was found."
ENDIF

Libraries: library.c , library.4th

C: NO_EVENT
4th: NO_EVENT

Type: Constant
Return Value: Long

The name of a value of the touchscreen property LAST_EVENT that indicates there was no touchscreen event.

if (Get_Property(GUI_TOUCHSCREEN(), LAST_EVENT)==NO_EVENT)
{
 printf("Last touchscreen event was no event.\n");
}

GUI_TOUCHSCREEN LAST_EVENT Get_Property NO_EVENT d=
IF
 CR ." Last touchscreen event was no event."
ENDIF

Libraries: library.c , library.4th

See also: PRESS_EVENT, HELD_EVENT, RELEASE_EVENT

C: NUM_OBJECTS
4th: NUM_OBJECTS

Type: Constant
Return Value: Integer

The name of a screen property that contains the number of objects currently loaded into a screen. This property is read only.

longNumObjects = Get_Property(GUI_SCREEN(), NUM_OBJECTS);

GUI_SCREEN NUM_OBJECTS Get_Property numObjects 2!

Libraries: library.c , library.4th

C: PALETTE
4th: PALETTE

Type: Constant
Return Value: Integer

The name of an object type used to create a new palette object. A palette, also known as the color table or look up table (LUT), is used to define the colors that are viewable on the display from the many different possible combinations of red, green, and blue. The color STN and color TFT displays are capable of showing 4096 colors (4 bits for red, green and blue) but even when using the highest bit depth of 8 bits per pixel, only 256 colors are available at any time. When converting color images using the Image Conversion Program, the palette (LUT) is extracted from the image, stored in the data file, and named in the header file with the image name plus "_LUT". To load a custom pallete see the example code below. Changing the palette will effect all of the color images loaded on every screen.

int paletteCustom;
paletteCustom = New_Object( PALETTE );
Set_Property( paletteCustom, PALETTE_DATA, IMAGE_NAME_LUT);
Set_Property(GUI_TOOLKIT(), DEFAULT_PALETTE, (long)paletteCustom);

VARIABLE paletteCustom
PALETTE New_Object paletteCustom !
paletteCustom PALETTE_DATA IMAGE_NAME_LUT Set_Property
GUI_TOOLKIT DEFAULT_PALETTE paletteCustom @ u>d Set_Property

Libraries: library.c , library.4th

C: PALETTE_DATA
4th: PALETTE_DATA

Type: Constant
Return Value: Integer

The name of a property of a palette object that contains the address of the palette data. The palette data defines the red, green, and blue values that are used to generate colors on the display. The address of the palette data is generated by the Mosaic's Image Conversion Program and stored in the Image Header File as a constant.

Set_Property(paletteCustom, PALETTE_DATA, IMAGE_LUT);

paletteCustom @ PALETTE_DATA IMAGE_LUT Set_Property

Libraries: library.c , library.4th

C: PEN_TYPE
4th: PEN_TYPE

Type: Constant
Return Value: Integer

The name of a pen property that determines whether the current shape (either a POINT or a LINE) is drawn or erased. Possible contents of this property include SET and UNSET. PEN_TYPE is initialized to SET by Initialize_GUI.

Set_Property(GUI_PEN(), PEN_TYPE, SET);

GUI_PEN PEN_TYPE SET Set_Property

Libraries: library.c , library.4th

C: PLOT
4th: PLOT

Type: Constant
Return Value: Integer

The name of an object type used to create a new plot object. A plot is used to render numerical data into graphical form onto a screen. New plot objects have a width of 240 pixels, a height of 120 pixels, and a buffer size for its data of 240 bytes. Plot objects can be resized using the Set_Property method along with the WIDTH_IN_PIXELS, HEIGHT_IN_PIXELS, and BUFFER_SIZE properties. Data is added to a plot buffer using the Add_Data method. The data is rendered onto a screen from the buffer when Refresh is called. We recommend you use the same value for the WIDTH_IN_PIXELS and BUFFER_SIZE properties.

plotVoltage = New_Object( PLOT );

PLOT New_Object plotVoltage !

Libraries: library.c , library.4th

C: PLOT_ERASE_WIDTH
4th: PLOT_ERASE_WIDTH

Type: Constant
Return Value: Long

The name of a plot property that controls how many pixels are erased ahead of each data point. When the plotted line wraps around the plot object, a width of this many pixels is maintained between the newest and oldest data points. Pixels in this range are set to the SCREEN_BACKGROUND color. Valid values are 2 to the width of the plot. This property must be set with Set_Property before any other property of the plot object.

plotHistogram = New_Object( PLOT );
Set_Property( plotHistogram, PLOT_ERASE_WIDTH, 2 );

PLOT New_Object plotHistogram !
plotHistogram @ PLOT_ERASE_WIDTH 2 Set_Property

Libraries: library.c , library.4th

See also: PLOT

C: PLOT_FULL
4th: PLOT_FULL

Type: Constant
Return Value: Integer

The name of an error that indicates the plot cannot accept any more data points; Call Refresh on GUI_SCREEN to allow more points to be added. The number of points that can be added at a time via Add_Data is limited by the 'Outstanding Data Points Constraint':

(buffer_size - plot_width + erase_width)

Calling Clear on the plot object temporarily lifts this constraint, and allows for 'buffer_size' points to be added. If the error occurs, the method simply drops the offending data point.

for( i =0; i < 10; i++ )
{
  Add_Data ( plotObject, rand()%PLOT_HEIGHT );
}
if ((Read_Error()>>16) == PLOT_FULL)
{
  printf("Plot is full. Refresh it.\n");
  Clear_Error();
}

10 0 DO
  plotObject @ RANDOM 119 UMOD Add_Data
LOOP
 
Read_Error NIP PLOT_FULL =
IF
  CR ." Plot is full. Refresh it."
  Clear_Error
ENDIF

Libraries: library.c , library.4th

C: POINT
4th: POINT

Type: Constant
Return Value: Long

The name of a value of the SHAPE property of the GUI_PEN() object. When the SHAPE property of the GUI_PEN() object is set to POINT, the Draw method draws a point or single pixel at the specified x and y location.

Set_Property(GUI_PEN(), SHAPE, POINT);

GUI_PEN SHAPE POINT Set_Property

Libraries: library.c , library.4th

See also: LINE

C: PRESS_EVENT
4th: PRESS_EVENT

Type: Constant
Return Value: Long

The name of a value of the touchscreen property LAST_EVENT that indicates a user has just touched the touchscreen.

if (Get_Property(GUI_TOUCHSCREEN(), LAST_EVENT)==PRESS_EVENT)
{
 printf("Last touchscreen event was a press event.\n");
}

GUI_TOUCHSCREEN LAST_EVENT Get_Property PRESS_EVENT d=
IF
 CR ." Last touchscreen event was a press event."
ENDIF

Libraries: library.c , library.4th

See also: HELD_EVENT, NO_EVENT, RELEASE_EVENT

C: PRESS_EVENT_PROCEDURE
4th: PRESS_EVENT_PROCEDURE

Type: Constant
Return Value: Integer

The name of a button property that contains the xcfa of a user defined press event procedure. The press event procedure is called each time the button receives a press event. Press event procedures can not take or return any parameters, but they can modify variables. PRESS_EVENT_PROCEDURE is uninitialized when a button is instantiated.

Set_Property( buttonStop, PRESS_EVENT_PROCEDURE, Stop_Process )

buttonStop @ PRESS_EVENT_PROCEDURE cfa.FOR Stop_Process Set_Property

Libraries: library.c , library.4th

See also: HELD_EVENT_PROCEDURE, RELEASE_EVENT_PROCEDURE

C: PRESS_GRAPHIC
4th: PRESS_GRAPHIC

Type: Constant
Return Value: Integer

The name of a button property that contains a reference to a graphic object that is drawn on a screen when the button receives a press event. PRESS_GRAPHIC is uninitialized when a button is instantiated.

Set_Property(buttonStop, PRESS_GRAPHIC, (long) graphicPress);

buttonStop @ PRESS_GRAPHIC graphicPress @ u>d Set_Property

Libraries: library.c , library.4th

See also: DRAW_GRAPHIC, RELEASE_GRAPHIC

C: PWM_DUTY_PERIOD_CH0
4th: PWM_DUTY_PERIOD_CH0

Type: Constant
Return Value: Integer

The name of a GUI_PWM_DAC() property that is used to set the pulse width modulation (PWM) output on pin 2 of the PWM / DAC Header. The duty is located in the 16 most significant bits and the period is located in the 16 least significant bits. Valid values for the period range from 2 to 255 corresponding to a period of 0.8 microseconds (1.25MHz) to 102 microseconds (9.803KHz). Valid values for the duty range from 1 to 255. To calculate the duty cycle, divide the duty by the period. For example, to generate a 4 microsecond period (250KHz) with a 40% duty cycle, use a value of 10 for the period (10 x 0.4 microseconds = 4 microseconds) and 4 for the duty (4/10 = 40%). No error checking is performed. This PWM output also controls the channel 0 digital to analog converter (DAC) output on pin 1 of the PWM / DAC Header.

Set_Property(GUI_PWM_DAC(), PWM_DUTY_PERIOD_CH0, (long) ((period<<16) | duty) );

GUI_PWM_DAC PWM_DUTY_PERIOD_CH0 duty @ period @ Set_Property

Libraries: library.c , library.4th

C: PWM_DUTY_PERIOD_CH1
4th: PWM_DUTY_PERIOD_CH1

Type: Constant
Return Value: Integer

The name of a GUI_PWM_DAC() property that is used to set the pulse width modulation (PWM) output on pin 4 of the PWM / DAC Header. The duty is located in the 16 most significant bits and the period is located in the 16 least significant bits. Valid values for the period range from 2 to 255 corresponding to a period of 0.8 microseconds (1.25MHz) to 102 microseconds (9.803KHz). Valid values for the duty range from 1 to 255. To calculate the duty cycle, divide the duty by the period. For example, to generate a 4 microsecond period (250KHz) with a 40% duty cycle, use a value of 10 for the period (10 x 0.4 microseconds = 4 microseconds) and 4 for the duty (4/10 = 40%). No error checking is performed. This PWM output also controls the channel 0 digital to analog converter (DAC) output on pin 3 of the PWM / DAC Header.

Set_Property(GUI_PWM_DAC(), PWM_DUTY_PERIOD_CH1, (long) ((period<<16) | duty) );

GUI_PWM_DAC PWM_DUTY_PERIOD_CH1 duty @ period @ Set_Property

Libraries: library.c , library.4th

C: PWM_DUTY_PERIOD_CH2
4th: PWM_DUTY_PERIOD_CH2

Type: Constant
Return Value: Integer

The name of a GUI_PWM_DAC() property that is used to set the pulse width modulation (PWM) output on pin 6 of the PWM / DAC Header. The duty is located in the 16 most significant bits and the period is located in the 16 least significant bits. Valid values for the period range from 2 to 255 corresponding to a period of 0.8 microseconds (1.25MHz) to 102 microseconds (9.803KHz). Valid values for the duty range from 1 to 255. To calculate the duty cycle, divide the duty by the period. For example, to generate a 4 microsecond period (250KHz) with a 40% duty cycle, use a value of 10 for the period (10 x 0.4 microseconds = 4 microseconds) and 4 for the duty (4/10 = 40%). No error checking is performed. This PWM output also controls the channel 0 digital to analog converter (DAC) output on pin 5 of the PWM / DAC Header.

Set_Property(GUI_PWM_DAC(), PWM_DUTY_PERIOD_CH2, (long) ((period<<16) | duty) );

GUI_PWM_DAC PWM_DUTY_PERIOD_CH2 duty @ period @ Set_Property

Libraries: library.c , library.4th

C: PWM_DUTY_PERIOD_CH3
4th: PWM_DUTY_PERIOD_CH3

Type: Constant
Return Value: Integer

The name of a GUI_PWM_DAC() property that is used to set the pulse width modulation (PWM) output on pin 8 of the PWM / DAC Header. The duty is located in the 16 most significant bits and the period is located in the 16 least significant bits. Valid values for the period range from 2 to 255 corresponding to a period of 0.8 microseconds (1.25MHz) to 102 microseconds (9.803KHz). Valid values for the duty range from 1 to 255. To calculate the duty cycle, divide the duty by the period. For example, to generate a 4 microsecond period (250KHz) with a 40% duty cycle, use a value of 10 for the period (10 x 0.4 microseconds = 4 microseconds) and 4 for the duty (4/10 = 40%). No error checking is performed. This PWM output also controls the channel 0 digital to analog converter (DAC) output on pin 7 of the PWM / DAC Header.

Set_Property(GUI_PWM_DAC(), PWM_DUTY_PERIOD_CH3, (long) ((period<<16) | duty) );

GUI_PWM_DAC PWM_DUTY_PERIOD_CH3 duty @ period @ Set_Property

Libraries: library.c , library.4th

C: RAW_COORDS
4th: RAW_COORDS

Type: Constant
Return Value: Integer

The name of a read only touchscreen property that contains the uncalibrated touchscreen readings of the last event. The raw coordinates are used by Calibrate to calibrate the touchscreen. The raw y value is located in the most significant 16 bits and the raw x value is located in the least significant 16 bits. This property is read only.

longCoords = Get_Property(GUI_TOUCHSCREEN(), RAW_COORDS);
raw_x = longCoords & 0xFFFF;
raw_y = longCoords >> 16;

GUI_TOUCHSCREEN RAW_COORDS Get_Property raw_y ! raw_x !

Libraries: library.c , library.4th

C: ulong Read_Error ( void )
4th: Read_Error ( -- u1 \ u2 | u1 = command, u2 = error code )

Type: Function
Return Value: An unsigned 32 bit number that represents the last reported error in the 16 most significant bits and the last command in the 16 least significant bits.

A method that passes a message to the slave processor telling the slave to return the last reported error and command. Clear_Error should be called after this method to prevent servicing the same error more than once. Clear_Error does not clear the command.

graphicStop = New_Object( GRAPHIC );
if ((Read_Error()>>16) == HEAP_FULL)
{
 printf("Can't create new object, heap is full.\n");
 Clear_Error();
}

GRAPHIC New_Object graphicStop !
Read_Error NIP HEAP_FULL =
IF
 CR ." Can't create new object, heap is full."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: RED
4th: RED

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to red if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)RED);

GUI_SCREEN SCREEN_BACKGROUND RED u>d Set_Property

Libraries: library.c , library.4th

C: void Redraw ( int screen_reference )
4th: Redraw( n -- | n = screen reference )

Type: Function

Input Parameters:

• screen_reference – A 16 bit number that refers to the screen object to be redrawn.

A method that passes a message to the slave processor telling the slave to redraw each object currently loaded into a screen. Does not read or modify the refresh flag of graphics, textboxes, or plots. Errors include: INVALID_SCREEN.

Redraw( GUI_SCREEN() );

GUI_SCREEN Redraw

Libraries: library.c , library.4th

C: void Refresh ( int screen_reference )
4th: Refresh ( n -- | n = screen reference )

Type: Function

Input Parameters:

• screen_reference – A 16 bit number that refers to the screen object to be refreshed.

A method that passes a message to the slave processor telling the slave to redraw only graphics, textboxes, or plots loaded into the specified screen which have their refresh property set to true. The refresh property of a graphic is set to true when the image of a graphic is modified. The refresh property of a textbox is set to true when string data is added, removed, or scrolled in a textbox. The refresh property of a plot is set to true when data is added to a plot or the plot is resized or cleared. Sets the refresh flag of the graphic, textbox, or plot to false once the objects have been redrawn. Errors include: INVALID_SCREEN.

Refresh( GUI_SCREEN() );

GUI_SCREEN Refresh

Libraries: library.c , library.4th

C: RELEASE_EVENT
4th: RELEASE_EVENT

Type: Constant
Return Value: Long

The name of a value of the touchscreen property LAST_EVENT that indicates a user has just removed their finger from the touchscreen.

if (Get_Property(GUI_TOUCHSCREEN(),LAST_EVENT)==RELEASE_EVENT)
{
 printf("Last touchscreen event was a release event.\n");
}

GUI_TOUCHSCREEN LAST_EVENT Get_Property RELEASE_EVENT d=
IF
 CR ." Last touchscreen event was a release event."
ENDIF

Libraries: library.c , library.4th

See also: HELD_EVENT, PRESS_EVENT

C: RELEASE_EVENT_PROCEDURE
4th: RELEASE_EVENT_PROCEDURE

Type: Constant
Return Value: Integer

The name of a button property that contains the xcfa of a user defined release event procedure. The release event procedure is called each time the button receives a release event. Release event procedures can not take or return any parameters, but they can modify variables. RELEASE_EVENT_PROCEUDRE is uninitialized when a button is instantiated.

Set_Property( buttonRun, RELEASE_EVENT_PROCEDURE, Run_Process )

buttonRun @ RELEASE_EVENT_PROCEDURE cfa.FOR Run_Process Set_Property

Libraries: library.c , library.4th

See also: HELD_EVENT_PROCEDURE, PRESS_EVENT_PROCEDURE

C: RELEASE_GRAPHIC
4th: RELEASE_GRAPHIC

Type: Constant
Return Value: Integer

The name of a button property that contains a reference to a graphic object that is drawn on a screen when the button receives a release event. RELEASE_GRAPHIC is uninitialized when a button is instantiated.

Set_Property(buttonStop, RELEASE_GRAPHIC, (long) graphicStop);

buttonStop @ RELEASE_GRAPHIC graphicStop @ u>d Set_Property

Libraries: library.c , library.4th

See also: DRAW_GRAPHIC, PRESS_GRAPHIC

C: RENDER
4th: RENDER

Type: Constant
Return Value: Integer

The name of a textbox property that enables or disables the rendering of the string in textbox. Setting the RENDER property to GUI_FALSE is useful when the textbox string needs to be changed but the changes do not need to be shown on the display. The RENDER property of a textbox is set to GUI_TRUE when the textbox is instantiated.

// Turn off the rendering of text in the textbox.
Set_Property(textboxString, RENDER, GUI_FALSE);
// Quickly add characters into the textbox.
Add_Character(textboxString, 'a');
Add_Character(textboxString, 'b');
Add_Character(textboxString, 'c');
// Turn on the rendering of text in the textbox, render added chars.
Set_Property(textboxString, RENDER, GUI_TRUE);

\ Turn off the rendering of text in the textbox
textboxString @ RENDER GUI_FALSE Set_Property
\ Quickly add characters into the textbox
textboxString @ ASCII a Add_Character
textboxString @ ASCII b Add_Character
textboxString @ ASCII c Add_Character
\ Turn on the rendering of text in the textbox, render added chars.
textboxString @ RENDER GUI_TRUE Set_Property

Libraries: library.c , library.4th

C: SCREEN
4th: SCREEN

Type: Constant
Return Value: Integer

The name of an object type used to create a new screen object whose data area resides outside of the display controller's RAM. Screens and display screens are objects that contain a collection of other functionally related objects such as graphics, buttons, textboxes, or plots. Screens can not be made visible by setting the display screen's VISIBLE property to GUI_TRUE. Rather, they must be copied to a display screen using Copy_Screen. GUI_SCREEN() is the visible display screen when the GUI Toolkit is initialized. When a screen is visible, its objects (graphics, buttons, textboxes, and plots) are shown on the display.

screenKeypad = New_Object( SCREEN );

SCREEN New_Object screenKeypad !

Libraries: library.c , library.4th

C: SCREEN_ADDRESS
4th: SCREEN_ADDRESS

Type: Constant
Return Value: Integer

The name of a read only screen property that contains the extended address of the screen's data buffer where images are drawn into.

longAddress = Get_Property(GUI_SCREEN(), SCREEN_ADDRESS);

GUI_SCREEN SCREEN_ADDRESS Get_Property address 2!

Libraries: library.c , library.4th

C: SCREEN_BACKGROUND
4th: SCREEN_GROUND

Type: Constant
Return Value: Integer

The name of a screen property that sets the background color of a screen by filling the screen's data area with the specified color. This will over-write the images any objects loaded in the screen; call Redraw to redraw the objects so that they will reappear. Initialized to BLACK when the screen is instantiated.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long) BLUE);

GUI_SCREEN SCREEN_BACKGROUND BLUE u>d Set_Property 

Libraries: library.c , library.4th

C: void Screen_Has_Changed ( void )
4th: Screen_Has_Changed ( -- )

Type: Function

A method that sets a global variable that indicates something on the currently visible screen has changed. Used with the Ether¬Smart Controller on applications that implement a web-based "remote front panel". Put this function into all button event procedures that modify the visible screen. The goal is to distinguish event procedures that simply darken and restore a button on the one hand, from event procedures that cause the contents of the screen to be different after the button press compared to before it. The flag set by this function is used by Simulated_Touch_To_Image to detect whether a time-consuming image conversion needs to be undertaken after the event procedure associated with the button press has executed. The flag set by this function is readable using Has_Screen_Changed, and is cleared by Simulated_Touch_To_Image upon a successful image conversion.

// Change screen to the pump screen by copying it to the visible screen
void Change_Screen_Event_Procedure ( void )
{
 Copy_Screen( screenPump, GUI_SCREEN() );
 // Re-enable the touchscreen by turning on the servicing of events.
 // The button must be configured to block on press.
 // We need to do this for buttons that change screens.
 Set_Property(GUI_TOOLKIT(), SERVICE_EVENTS, GUI_TRUE);
 // Since we changed screens, the screen has changed.
 Screen_Has_Changed();
}

\ Change screen to the pump screen by copying it to the visible screen.
: Change_Screen_Event_Procedure ( -- )
  screenPump @ GUI_SCREEN Copy_Screen
  \ Re-enable the touchscreen by turning on the servicing of events.
  \ The button must be configured to block on press.
  \ We need this for buttons that change screens.
  GUI_TOOLKIT SERVICE_EVENTS GUI_TRUE Set_Property
  \ Since we changed screens, the screen has changed.
  Screen_Has_Changed
;

Libraries: library.c , library.4th

See also: Has_Screen_Changed, Simulated_Touch_To_Image

C: int Screen_To_Image ( xaddr buffer, long buffer_size, int format )
4th: Screen_To_Image( xaddr \ d \ n1 – n2 | xaddr = buffer, d = buffer size, n1 = format, n2 = error )

Type: Function

Input Parameters:

• buffer – The extended address (xaddr) of the buffer in RAM that the image will be written into.
• buffer_size – A 32 bit number that specifies the size of the buffer in bytes.
• format – A 16 bit integer that specifies the format of the image. For now, only the BMP_FORMAT is allowed.

Return Value: A 16 bit number that contains the error return value.

A method that passes a message to the slave processor telling the slave to convert the currently visible screen into an image and then send the image to the specified buffer xaddr in RAM on the master. The number of bytes stored into the buffer is limited to the specified buffer_size parameter. The first 4 bytes stored in the buffer contain a 32-bit byte count, followed by the image data in the specified format. Currently, the only valid format is the BMP_FORMAT, corresponding to the bitmap format For a bit depth of 1 bit per pixel, the buffer size must be at least 9668 bytes. For a bit depth of 4 bits per pixel, the buffer size must be at least 38524 bytes. For a bit depth of 8 bits per pixel, the buffer size must be at least 77,884 bytes. This function returns the following error codes: NO_ERROR, INVALID_IMAGE_FORMAT, and BUFFER_SIZE_TO_SMALL.

switch(Screen_To_Image(my_buffer, buffer_size, BMP_FORMAT))
{
 case NO_ERROR:              printf("No error.\n");                 break;
 case INVALID_IMAGE_FORMAT:  printf("Invalid format.\n");           break;
 case BUFFER_SIZE_TOO_SMALL: printf("Buffer size is too small.\n"); break;
}

my_buffer x@ buffer_size 2@ BMP_FORMAT Screen_To_Image
CASE
 NO_ERROR              OF ." No error."                 CR ENDOF
 INVALID_IMAGE_FORMAT  OF ." Invalid format."           CR ENDOF
 BUFFER_SIZE_TOO_SMALL OF ." Buffer size is too small." CR ENDOF
ENDCASE

Libraries: library.c , library.4th

See also: Graphic_To_Image, Simulated_Touch_To_Image

C: SCREEN_UNCHANGED
4th: SCREEN_UNCHANGED

Type: Constant
Return Value: Integer

The name of a Simulated_Touch_To_Image return value that indicates the screen has not changed so a new screen image is not available. Does not indicate an error condition; used to optimize application code by not using an unchanged screen image.

switch(Simulated_Touch_To_Image(my_buffer,buffer_size,BMP_FORMAT,x,y))
{
 case NO_ERROR:              printf("No error.\n");                    break;
 case INVALID_IMAGE_FORMAT:  printf("Invalid format.\n");              break;
 case BUFFER_SIZE_TOO_SMALL: printf("Buffer size is too small.\n");    break;
 case SCREEN_UNCHANGED:      printf("Screen is unchanged.\n");         break;
 case XY_NOT_IN_BUTTON:      printf("x and y coordinates do not lie within a button.\n"); break;
}

my_buffer x@ buffer_size 2@ BMP_FORMAT x @ y @ Simulated_Touch_To_Image
CASE
 NO_ERROR              OF ." No error."                                       CR ENDOF
 INVALID_IMAGE_SIZE    OF ." Invalid format."                                 CR ENDOF
 BUFFER_SIZE_TOO_SMALL OF ." Buffer size is too small."                       CR ENDOF
 SCREEN_UNCHANGED      OF ." Screen is unchanged."                            CR ENDOF
 XY_NOT_IN_BUTTON      OF ." x and y coordinates do not lie within a button." CR ENDOF
ENDCASE

Libraries: library.c , library.4th

See also: Simulated_Touch_To_Image

C: SERVICE_EVENTS
4th: SERVICE_EVENTS

Type: Constant
Return Value: Integer

The name of a GUI Toolkit property that determines if touchscreen events are serviced and event procedures are called. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. SERVICE_EVENTS is set to GUI_TRUE by Initialize_GUI.

Set_Property(GUI_TOOLKIT(), SERVICE_EVENTS, GUI_FALSE);

GUI_TOOLKIT SERVICE_EVENTS GUI_FALSE Set_Property

Libraries: library.c , library.4th

C: void Service_GUI_Events ( void )
4th: Service_GUI_Events ( -- )

Type: Function

A method that looks for messages from the slave processor that indicate a user defined event procedure needs to be executed. In a typical application, this method must be included in a task, as part of the tasks infinite loop to service events generated from the touchscreen.

Service_GUI_Events();

Service_GUI_Events

Libraries: library.c , library.4th

C: SET
4th: SET

Type: Constant
Return Value: Long

The name of a value of the PEN_TYPE property of the GUI_PEN() object. When the PEN_TYPE property of the GUI_PEN() object is SET, the Draw method draws (as opposed to erases) a point or a line.

Set_Property(GUI_PEN(), PEN_TYPE, SET);

GUI_PEN PEN_TYPE SET Set_Property

Libraries: library.c , library.4th

See also: UNSET

C: void Set_Property ( int object_reference, int property, ulong value )
4th: Set_Property( n1 \ n2 \ ud -- | n1 = object reference, n2 = property, ud = value )

Type: Function

Input Parameters:

• object_reference – An 16 bit variable that refers to the object whose property is being set.
• property – A 16 bit number that specifies the property to be set.
• value – An unsigned 32 bit number that specifies the value of the property. All property values are 32 bits.

A method that passes a message to the slave processor telling the slave to set the value of a property of an object. Possible errors include: INVALID_HEADER, INVALID_OBJECT, INVALID_PROPERTY, INVALID_GRAPHIC, INVALID_FONT, INVALID_TEXTBOX, HEIGHT_OUT_OF_RANGE, WIDTH_OUT_OF_RANGE.

Set_Property(GUI_PEN(), PEN_TYPE, SET);

GUI_PEN PEN_TYPE SET Set_Property

Libraries: library.c , library.4th

See also: Get_Property

C: SHAPE
4th: SHAPE

Type: Constant
Return Value: Integer

The name of a pen property that specifies the current shape drawn or erased by the Draw method. Possible contents of this property are POINT and LINE. SHAPE is initialized to POINT by Initialize_GUI.

Set_Property(GUI_PEN(), SHAPE, LINE);

GUI_PEN SHAPE LINE Set_Property

Libraries: library.c , library.4th

C: int Simulated_Touch_To_Image( xaddr buffer, long buffer_size, int format, int x_coord, int y_coord)
4th: Simulated_Touch_To_Image ( xaddr \ d \ n1 \ n2 \ n3 – n4 | xaddr = buffer, d = buffer size, n1 = format, n2 = x coord, n3 = y coord, n4 = error )

Type: Function

Input Parameters:

• buffer – The extended address (xaddr) of the buffer in RAM that the image will be written into.
• buffer_size – A 32 bit number that specifies the size of the buffer in bytes.
• format – A 16 bit integer that specifies the format of the image. For now, only the BMP_FORMAT is allowed.
• x_coord – A 16 bit integer that specifies the x coordinate in pixels of the simulated touchscreen press.
• y_coord – A 16 bit integer that specifies the y coordinate in pixels of the simulated touchscreen press.

Return Value: A 16 bit number that contains the error return value.

A method typically used with the EtherSmart or Wifi Wildcard to implement a web-based "remote front panel". Call this function after a click on an imagemap (a clickable screen image on a webpage) and before sending the new or refreshed screen to a waiting browser. If the specified x and y coordinates (in units of pixels, relative to the upper left corner of the screen) are within the active area of a button on the visible screen, this function sends a message to the slave processor telling it to draw the button's press graphic, draw the button's release graphic, and execute the button's press event procedure. If the button's press event procedure changes the screen, this routine invokes Screen_To_Image to create a bitmap version of the current screen located at the specified buffer extended address in RAM, and limited to the specified maximum buffer_size. If the user-defined press event procedure changes the screen image, it must invoke the Screen_Has_Changed function in the press event procedure so that this function will be aware that the screen image must be regenerated. The first 4 bytes stored in the buffer contain a 32-bit byte count, followed by the image data in the specified format. Currently, the only valid format is the BMP_FORMAT, corresponding to the bitmap format For a bit depth of 1 bit per pixel, the buffer size must be at least 9668 bytes. For a bit depth of 4 bits per pixel, the buffer size must be at least 38524 bytes. For a bit depth of 8 bits per pixel, the buffer size must be at least 77,884 bytes. This function returns the following error codes: NO_ERROR, INVALID_IMAGE_FORMAT, BUFFER_SIZE_TOO_SMALL, SCREEN_UNCHANGED, and XY_NOT_IN_BUTTON.

switch(Simulated_Touch_To_Image(my_buffer,buffer_size,BMP_FORMAT,x,y))
{
 case NO_ERROR:              printf("No error.\n");                  break;
 case INVALID_IMAGE_FORMAT:  printf("Invalid format.\n");            break;
 case BUFFER_SIZE_TOO_SMALL: printf("Buffer size is too small.\n");  break;
 case SCREEN_UNCHANGED:      printf("Screen is unchanged.\n");       break;
 case XY_NOT_IN_BUTTON:      printf("x and y coordinates do not lie within a button.\n"); break;
}

my_buffer x@ buffer_size 2@ BMP_FORMAT x @ y @ Simulated_Touch_To_Image
CASE
 NO_ERROR              OF ." No error."                                       CR ENDOF
 INVALID_IMAGE_SIZE    OF ." Invalid format."                                 CR ENDOF
 BUFFER_SIZE_TOO_SMALL OF ." Buffer size is too small."                       CR ENDOF
 SCREEN_UNCHANGED      OF ." Screen is unchanged."                            CR ENDOF
 XY_NOT_IN_BUTTON      OF ." x and y coordinates do not lie within a button." CR ENDOF
ENDCASE

Libraries: library.c , library.4th

See also: Screen_Has_Changed, Screen_To_Image, Simulate_Touch

C: xaddr Simulate_Touch ( int x, int y )
4th: Simulate_Touch ( n1 \ n2 – xaddr | n1 = x coordinate, n2 = y coordinate, xaddr = event procedure xcfa )

Type: Function

Input Parameters:

• x – A 16 bit number that specifies the x coordinate in pixels of the simulated touchscreen press.
• y – A 16 bit number that specifies the y coordinate in pixles of the simulated touchscreen press.

Return Value: A 32 bit xcfa of the press event procedure of the button whose active area contained the x and y coordinate pair.

A method used to simulate a touchsceen press. If the specified x and y coordinates (in units of pixels, relative to the upper left corner of the screen) are within the active area of a button on the current screen, sends a message to the slave processor telling it to draw the button's press graphic, draw the button's release graphic, and return the button's press event procedure (if present). Otherwise returns a 32-bit zero. This function can be used in conjunction with the Ether¬Smart Controller to create an imagemap (a clickable web image) of the screen to implement a web-based "remote front panel". Most applications will not directly call this function, instead using the high-level function Simulated_Touch_To_Image to implement the remote front panel feature.

xaddr button_handler = Simulate_Touch( x, y );
if (button_handler)
{
  Execute(button_handler);
}

x_coord @ y_coord @ Simulate_Touch XDUP
0\0 d<>
IF
 EXECUTE
ENDIF

Libraries: library.c , library.4th

See also: Simulated_Touch_To_Image

C: STRING_LENGTH
4th: STRING_LENGTH

Type: Constant
Return Value: Integer

The name of a read only textbox property that contains the number of characters contained in the string in the textbox.

longLength = Get_Property ( textboxString, STRING_LENGTH ); 

textboxString @ STRING_LENGTH Get_Property len 2!

Libraries: library.c , library.4th

C: STRING_LINES
4th: STRING_LINES

Type: Constant
Return Value: Integer

The name of a read only textbox property that contains the number of lines the string in the textbox occupies when rendered. Based on the number of characters in the string and the width of the textbox.

longNumLines = Get_Property ( textboxString, STRING_LINES ); 

textboxString @ STRING_LINES Get_Property num_lines 2!

Libraries: library.c , library.4th

C: void String_To_Textbox ( int object_reference, char *string, int count )
4th: String_To_Textbox ( n \ xaddr \ count -- | n = object reference, xaddr = string to write into textbox, count = count of string )

Type: Function

Input Parameters:

• object_reference – A 16 bit value referring to the textbox that the string is written to.
• string – Extended string address of the first character of string to be written into the textbox.
• count – The number of characters in the string

A method that passes a message to the slave processor telling the slave to write a string into a textbox. String_To_Textbox overwrites any previous string data. To add or delete characters to the end of the string, use the Add_Character and Delete_Character methods. The height and width of the textbox must be initialized before a string is written into it. Errors include: HEAP_FULL, HEIGHT_OUT_OF_RANGE, INVALID_TEXTBOX, WIDTH_OUT_OF_RANGE.

char* hi_string = "Hello World";
String_To_Textbox(textboxInfo, hi_string, sizeof(hi_string));

textboxInfo @ " Hello World" String_To_Textbox

Libraries: library.c , library.4th

See also: STRING_TO_TEXTBOX, Textbox_To_String

C: void STRING_TO_TEXTBOX ( int object_reference, char *string )

Type: C Macro

Input Parameters:

• object_reference – A 16 bit value referring to the textbox that the string is written to.
• string – Extended string address of the first character of string to be written into the textbox.

A macro that invokes the function String_To_Textbox, emplacing the size of the string as the count in the parameter list. String_To_Textbox is a method that passes a message to the slave processor telling the slave to write a string into a textbox; see its glossary entry. This macro simplifies syntax because the quoted string can be simply placed in the parameter list of the macro.

String_To_Textbox(textboxInfo, "Hello World");

Libraries: library.c See also: String_To_Textbox, Textbox_To_String

C: TARGET_SCREEN
4th: TARGET_SCREEN

Type: Constant
Return Value: Integer

The name of a pen property that contains the screen that the pen object renders to with the Draw method. TARGET_SCREEN is initialized to GUI_SCREEN() by Initialize_GUI.

Set_Property(GUI_PEN(), TARGET_SCREEN, (long) GUI_SCREEN());

GUI_PEN TARGET_SCREEN GUI_SCREEN u>d Set_Property

Libraries: library.c , library.4th

C: TEXTBOX
4th: TEXTBOX

Type: Constant
Return Value: Integer

The name of an object type used to create a new textbox object. A textbox employs a font object to render strings onto a screen. New textbox objects do not have their size set when they are instantiated, have their RENDER property set to GUI_TRUE, BORDER property set to GUI_FALSE, and uses the DEFAULT_FONT to render text. The size of textbox objects can only be set once using the Set_Property method along with the WIDTH_IN_PIXELS or HEIGHT_IN_PIXELS properties. The size and font (if different from the DEFAULT_FONT) of the textbox must be set before strings or characters are written into the textbox. Textboxes can not be larger than 320 pixels wide by 240 tall. The font of a textbox can be changed using the Set_Property method with the TEXTBOX_FONT property.

textboxInfo = New_Object ( TEXTBOX );

TEXTBOX New_Object textboxInfo !

Libraries: library.c , library.4th

C: TEXTBOX_BACKGROUND
4th: TEXTBOX_BACKGROUND

Type: Constant
Return Value: Integer

The name of a textbox property that sets the background color of a textbox. TEXTBOX_BACKGROUND is initialized to BLACK when a textbox is instantiated. This property must be set before the textbox is sized and before a string is written into the textbox.

Set_Property(textboxInfo, TEXTBOX_BACKGROUND, (long) BLUE);

textboxInfo @ TEXTBOX_BACKGROUND BLUE u>d Set_Property

Libraries: library.c , library.4th

C: TEXTBOX_FONT
4th: TEXTBOX_FONT

Type: Constant
Return Value: Integer

The name of a textbox property that contains the object reference to the font used to render string data in a textbox onto a screen. TEXTBOX_FONT is initialized to the DEFAULT_FONT when a textbox is instantiated. The DEFAULT_FONT is initialized to the GUI_FONT() by Initialize_GUI. The GUI_FONT() is custom proportional font with a height of 10 pixels. Changing the DEFAULT_FONT to a custom font causes the custom font to be used as the textbox font for all subsequently created textboxes. Use this property to change the font of only one textbox.

Set_Property(textboxInfo, TEXTBOX_FONT, (long) fontCustom);

textboxInfo @ TEXTBOX_FONT fontCustom @ u>d Set_Property

Libraries: library.c , library.4th

C: TEXTBOX_ROWS
4th: TEXTBOX_ROWS

Type: Constant
Return Value: Integer

The name of a read only textbox property that contains the number of rows of the textbox. The number of rows of a textbox is equal to the height of the textbox in pixels divided by the height of the TEXTBOX_FONT.

longRows = Get_Property(textboxInfo, TEXTBOX_ROWS);

textboxInfo @ TEXTBOX_ROWS Get_Property longRows 2!

Libraries: library.c , library.4th

C: TEXTBOX_SIZE_OUT_OF_RANGE
4th: TEXTBOX_SIZE_OUT_OF_RANGE

Type: Constant
Return Value: Integer

The name of an error that indicates the width of a textbox object in pixels multiplied by its height is greater than 65536, the size of a 16 bit integer. This error can only occur when operating in 8 bit color. If the error occurs, the method recovers from the error by using the maximum size that will fit in a 16 bit integer.

int plotHeader;
Initialize_GUI ( COLOR_STN, 8 );
plotHeader = New_Object( TEXTBOX );
Set_Property( plotHeader, HEIGHT_IN_PIXELS, 205 );
Set_Property( plotHeader, WIDTH_IN_PIXELS, 320 );  // 205 * 320 = 65600
if ((Read_Error()>>16) == TEXTBOX_SIZE_OUT_OF_RANGE)
{
  printf("The width * height of textbox (in bytes) cannot fit into a 16bit integer.\n");
  Clear_Error();
}

VARIABLE plotHeader
 
COLOR_STN 8 Initialize_GUI
TEXTBOX New_Object plotHeader !
plotHeader @ HEIGHT_IN_PIXELS 205 u>d Set_Property
plotHeader @ WIDTH_IN_PIXELS 320 u>d Set_Property  \ 205 * 320 = 65600
Read_Error NIP TEXTBOX_SIZE_OUT_OF_RANGE =
IF
 CR ." The width * height of textbox (in bytes) cannot fit into a 16bit integer."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: char *Textbox_To_String ( int object_reference )
4th: Textbox_To_String ( n – x$addr | n = object reference )

Type: Function

Input Parameters:

• object_reference – A 16 bit variable that refers to the textbox that the string is read from.

Return Value: The pointer to a character string requested from the specified textbox. An uncounted null (0) character is postpended to the string so that the C sizeof function works on the returned string. The extended string address of the string requested from the textbox.

A method that passes a message to the slave processor telling the slave to read up to 120 characters from a textbox. Errors include INVALID_TEXTBOX. An uncounted null (0) character is postpended to the string so that the C sizeof function works on the returned string.

intSetting = atoi(Textbox_To_String(textboxInfo));

textboxInfo @ Textbox_To_String
$>f \ convert string into floating point number
IF \ if the conversion was successful,
 f.  \ print out the floating point number
ENDIF

Libraries: library.c , library.4th

See also: STRING_TO_TEXTBOX

C: TOUCHSCREEN_INITIALIZATION_FAILURE
4th: TOUCHSCREEN_INITIALIZATION_FAILURE

Type: Constant
Return Value: Integer

The name of an error that indicates there was an error initializing the touchscreen controller. This error indicates there was a hardware failure. Please contact Mosaic Industries for a Return Material Authorization.

Initialize_GUI(COLOR_TFT, 4);
if ((Read_Error()>>16) == TOUCHSCREEN_INITIALIZATION_FAILURE)
{
 printf("Touchscreen initialization failure.\n");
 Clear_Error();
}

COLOR_TFT 4 Initialize_GUI
Read_Error NIP TOUCHSCREEN_INITIALIZATION_FAILURE =
IF
 CR ." Touchscreen initialization failure."
 Clear_Error
ENDIF

Libraries: library.c , library.4th

C: void Un_Load ( int screen_reference, int object_reference, int x, int y )
4th: Un_Load ( n1 \ n2 \ n3 \ n4 -- | n1 = screen reference, n2 = object reference, n3 = x coordinate, n4 = y coordinate )

Type: Function

Input Parameters:

• screen_reference – A 16 bit variable that refers to the screen object that the object specified by object_reference will be unloaded from.
• object_reference – A 16 bit variable that refers to the object that will be unloaded from the screen.
• x_coordinate – A 16 bit number that specifies the location of the left edge of the object in the horizontal direction relative to the left edge of the screen. The x-coordinate must be the same coordinate used with the Load method.
• y_coordinate – A 16 bit number that specifies the location of the top of the object in the vertical direction relative to the top edge of the screen. The y-coordinate must be the same coordinate used with the Load method.

A method that passes a message to the slave processor telling the slave to unload an object from a screen and erase the image of the object from the screen. The x and y coordinates must be the same x and y coordinates that were used to load the object into the screen. Errors include: INVALID_SCREEN, INVALID_OBJECT, X_OUT_OF_RANGE, and Y_OUT_OF_RANGE.

Un_Load(GUI_SCREEN(), buttonStop, 0, 0);

GUI_SCREEN buttonStop @ 0 0 Un_Load

Libraries: library.c , library.4th

See also: Load

C: UNSET
4th: UNSET

Type: Constant
Return Value: Long

The name of a value of the PEN_TYPE property of the GUI_PEN() object. When the PEN_TYPE property of the GUI_PEN() object is UNSET, the Draw method erases a point or a line from a screen.

Set_Property(GUI_PEN(), PEN_TYPE, UNSET);

GUI_PEN PEN_TYPE UNSET Set_Property

Libraries: library.c , library.4th

See also: SET

C: VERTICAL_SNAP_TO_GRID
4th: VERTICAL_SNAP_TO_GRID

Type: Constant
Return Value: Integer

The name of a property of the GUI Toolkit that aligns objects loaded onto a screen onto a vertical grid. The grid size is 8 pixels for a bit depth of 1 pbb, 2 pixels for a bit depth of 4 bpp, and 1 pixel for a bit depth of 8 bpp. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. VERTICAL_SNAP_TO_GRID is initialized to GUI_FALSE by Initialize_GUI.

Set_Property(GUI_TOOLKIT(), VERTICAL_SNAP_TO_GRID, GUI_FALSE);

GUI_TOOLKIT VERTICAL_SNAP_TO_GRID GUI_FALSE Set_Property

Libraries: library.c , library.4th

See also: HORIZONTAL_SNAP_TO_GRID

C: VISIBLE
4th: VISIBLE

Type: Constant
Return Value: Integer

The name of a display screen property that indicates if the screen is shown on the display. Only one display screen can be visible at a time. Possible contents of this property are the booleans GUI_TRUE and GUI_FALSE. GUI_SCREEN() is the visible screen after Initialize_GUI is called.

Set_Property(displayScreenPump, VISIBLE, GUI_TRUE);

displayScreenPump @ VISIBLE GUI_TRUE Set_Property

Libraries: library.c , library.4th

C: WHITE
4th: WHITE

Type: Constant
Return Value: Integer

A constant used to set the background of a screen or textbox, the pixel or line color of the GUI_PEN(), or the color of a font to white if the default color palette is used.

Set_Property(GUI_SCREEN(), SCREEN_BACKGROUND, (long)WHITE);

GUI_SCREEN SCREEN_BACKGROUND WHITE u>d Set_Property

Libraries: library.c , library.4th

C: WIDTH_IN_PIXELS
4th: WIDTH_IN_PIXELS

Type: Constant
Return Value: Integer

The name of a property that contains the width in pixels of a screen, button, textbox, graphic, or plot.

longWidth = Get_Property(GUI_SCREEN(), WIDTH_IN_PIXELS);