The EtherSmart Wildcard Glossary

<< Previous |

GUI Toolkit Functions for a Remote Front Panel

C:   void Globalize_TVars ( GUI_VARS * tvars_addr, page tvars_page )

4th: Globalize_TVars ( tvars_address\tvars_page -- )

      Initializes a global variable to contain the 32-bit extended base xaddress of the tvars structure.  This function must be called at initialization time for the GUI Toolkit of the Qscreen product in order to implement the web-based “remote front panel” feature. This function need not be called if other versions of the GUI Toolkit are used (QVGA Board, PDQScreen, etc.)  This function is required for use with the Qscreen so that the functions Screen_To_Image, Simulate_Touch, and Simulated_Touch_To_Image will have the same stack picture reguardless of the GUI Toolkit being used.

C:   int Graphic_To_Image ( xaddr xgraphic, xaddr xbuffer, uint buffer_size, int format_id )

4th: Graphic_To_Image ( xgraphic\xbuffer\buffer_size\format_id -- error )

      Converts the graphic object at the 32-bit xaddress xgraphic into an image at the specified 32-bit RAM xaddress xbuffer. The number of bytes stored in xbuffer is limited to the specified buffer_size parameter. The first 4 bytes stored at xbuffer contain a 32-bit byte count, followed by the image data in the specified format. The default format_id is 1, corresponding to the bitmap (bmp) format (you can use the constant HTTP_IMAGE_BITMAP_CONTENT).  Future versions of the GUI Toolkit for color screens will support a format_id = 2 which converts the color image to a monochrome bitmap image to save memory space and data transfer time.  Images must be representable in 65,535 or fewer bytes. This limits full-size quarter-VGA color graphics to 4 bit-per-pixel color depth.  This function returns an error value with the following meaning:

                    Error value Meaning

                    0                      no error

                    1                      invalid format_id

                    2                      buffer_size is too small for the specified xgraphic

                    3                      invalid xgraphic

      Note: After this routine executes, a standard “LBuffer” comprising a 2-byte count followed by the data is present at the xbuffer+2 xaddress.

C:   int Has_Screen_Changed ( void )

4th: Has_Screen_Changed ( -- flag )

      Reports the value of the boolean flag that tells whether the screen image has been updated.  This flag is set by Screen_Has_Changed (see its glossary entry), and is cleared by Screen_To_Image and 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 undertaken after the GUI handler function 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.

C:   void Screen_Has_Changed ( void )

4th: Screen_Has_Changed ( -- )

      Sets a global variable that indicates something on the current screen has changed.  If your application implements a web-based “remote front panel” capability, code this function into each user-defined GUI Toolkit button handler that modifies the displayed screen.  The goal is to distinguish button handlers that simply darken and restore a button on the one hand, from button handlers that cause the contents of the screen to be different after the button press compared to before it.  The flag set by this variable is used by Simulated_Touch_To_Image to detect whether a time-consuming image conversion needs to be undertaken after the GUI handler function associated with a button press has executed. The flag set by this function is readable using Has_Screen_Changed, and is cleared by Screen_To_Image and Simulated_Touch_To_Image upon a successful image conversion.

C:   int Screen_To_Image ( xaddr xbuffer, uint buffer_size, int format_id )

4th: Screen_To_Image ( xbuffer\buffer_size\format_id -- error )

      Converts the current contents of the displayed screen into an image at the specified 32-bit RAM xaddress xbuffer. The number of bytes stored in xbuffer is limited to the specified buffer_size parameter. The first 4 bytes stored at xbuffer contain a 32-bit byte count, followed by the image data in the specified format. The default format_id is 1, corresponding to the bitmap (bmp) format (you can use the constant HTTP_IMAGE_BITMAP_CONTENT).  Future versions of the GUI Toolkit for color screens will support a format_id = 2 which converts the color image to a monochrome bitmap image to save memory space and data transfer time.  Images must be representable in 65,535 or fewer bytes.  This limits quarter-VGA images to either monochrome or 4 bit-per-pixel color depth. If the image was successfully created, this function clears the “screen has changed” flag; see Screen_Has_Changed and Has_Screen_Changed.  This function returns an error value with the following meaning:

                    Error value Meaning

                    0                      no error

                    1                      invalid format_id

                    2                      buffer_size is too small for the specified xgraphic

      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.

      Note: After this routine executes, a standard “LBuffer” comprising a 2-byte count followed by the data is present at the xbuffer+2 xaddress.

      QScreen Notes: Globalize_TVars must be called at initialization time before using this routine on the Qscreen product. The QScreen buffer_size parameter must be at least 4160 bytes (bmp file size) + 3840 rendered text buffer size = 8000 bytes minimum for the QScreen. 

      QVGA Board Notes: The buffer_size parameter must be at least 9668 bytes to support the QVGA screen.

      PDQScreen Notes: The buffer_size parameter must be at least 9668 bytes to support the PDQScreen in monochrome mode, and must be at least 38532 bytes to support a 4-bits per pixel color screen.

C:   int Simulated_Touch_To_Image ( xaddr xbuffer, uint buffer_size, int format_id, int x, int y )

4th: Simulated_Touch_To_Image ( xbuffer\buffer­_size\format_id \x\y -- result )

      To implement a web-based “remote front panel” for your instrument, call this function after a click on an “imagemap” clickable webpage screen image, 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 current screen, this function draws the button's press graphic, draws the button's release graphic, and executes the button’s “press” handler function. If the button handler changes the screen, this routine invokes Screen_To_Image to create a bitmap version of the current screen located at the specified xbuffer extended address in RAM, and limited to the specified maximum buffer_size. If the user-defined button handler changes the screen image, it must invoke the Screen_Has_Changed function in the “press” button handler so that this function will be aware that the screen image must be regenerated. The default format_id is 1, corresponding to the bitmap (bmp) format (you can use the constant HTTP_IMAGE_BITMAP_CONTENT).  Future versions of the GUI Toolkit for color screens will support a format_id = 2 which converts the color image to a monochrome bitmap image to save memory space and data transfer time.  Images must be representable in 65,535 or fewer bytes.  This function returns a result code with the following meaning:

                    Result value       Meaning

                    0                      no error, screen image has been updated

                    1                      invalid format_id

                    2                      buffer_size is too small for the specified xgraphic

                    0x8000              screen image has not been updated

                    0x8001              screen image unchanged because x,y are not within a button

      Note that the 0x8000 and 0x8001 values can be tested for with a “less than 0” test; these results do not necessarily indicate an error condition, but may be useful in optimizing the application code.  A typical web/GUI application program will test that the error result = 0 and, if so, serve the updated image to the browser.

      Note: After this routine executes, a standard “LBuffer” comprising a 2-byte count followed by the data is present at the xbuffer+2 xaddress.

      QScreen Notes: Globalize_TVars must be called at initialization time before using this routine on the Qscreen product. The QScreen buffer_size parameter must be at least 4160 bytes (bmp file size) + 3840 rendered text buffer size = 8000 bytes minimum for the QScreen. 

      QVGA Board Notes: The buffer_size parameter must be at least 9664 bytes to support the QVGA screen.

      PDQScreen Notes: The buffer_size parameter must be at least 9664 bytes to support the PDQScreen in monochrome mode, and must be at least 38644 bytes to support a 4-bits per pixel color screen.

C:   xaddr Simulate_Touch ( int x, int y )

4th: Simulate_Touch ( x\y -- handler_xcfa )

      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, draws the button's press graphic, draws the button's release graphic, and returns the button's press handler (if present). Otherwise returns a 32-bit zero.  This function can be used in conjunction with an “imagemap” clickable web image of the screen to implement a web-based “remote front panel” for the instrument.  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.

      QScreen Notes: Globalize_TVars must be called at initialization time before using this routine on the Qscreen product; Globalize_TVars is not needed for other platforms.

<< Previous |