Chapter 3 - Functional Overview of GUIX

The strings assigned to your GUIX widgets which support text display can be statically defined string constants, which are normally placed in constant storage as part of the GUIX String table described below, and dynamically defined strings, which are strings generated at runtime using services such as sprintf or gx_utility_ltoa.

Examples of dynamic strings might include a value displayed as a number within a GUIX prompt widget, or a "time / date" string which is dynamically formatted based on the user’s location and format preferences. If you create strings at runtime which will be assigned to GUIX widgets such as GX_PROMPT or GX_TEXT_BUTTON widgets, you must choose to either statically allocate the storage for these runtime generated strings (i.e global character arrays), or you can define and install a dynamic memory allocator function and use the GX_STYLE_TEXT_COPY style, which instructs those widgets to create a private copy of text strings assigned.

It is a programming error to use temporary storage, such as an automatic character array, to hold a dynamically generated string and then assign this string to a widget that does not have the GX_STYLE_TEXT_COPY style. When this style is not enabled, the widget simply copies the provided string pointer, and the string data must be statically allocated or the widget string pointer will likely end up pointing at garbage data producing unpredictable results.

The GUIX API functions which accept a GX_STRING parameter always verify that the length of the string pointed to by the GX_STRING.gx_string_ptr field match the value of the GX_STRING.gx_string_length field. If the two fields are not consistent, a GX_INVALID_STRING_LENGTH error is returned and the API called returns without accepting the string assignment.

For safety considerations the GUIX software never internally uses the standard C string functions such as strlen or strcpy. These functions have been known to be susceptible to malicious attacks when string data is acquired dynamically which is often the case with connected applications.

GUIX library releases prior to release 5.6 defined API functions which accepted (GX_CONST GX_CHAR *text) as a parameter. These functions, while still supported for backwards compatibility, have been obsoleted and replaced by the preferred API functions which accept (GX_CONST GX_STRING *string) as an input parameter.

By default, the deprecated text handling API is enabled allowing all previously written applications to build cleanly with the latest updates to the GUIX library. To disable the deprecated text handling API, the definition GX_DISABLE_DEPRECATED_STRING_API should be added to the gx_user.h header file. All new applications should define GX_DISABLE_DEPRECATED_STRING_API and should use only the replacement API functions. All output files generated by GUIX Studio for GUIX library version release 5.6 or later will utilize only the replacement API functions.

The following table lists the deprecated and newly defined replacement API function names:

The GUIX string table and string resources are registered with a GUIX display instance.

Each display in a multi-display system has its own string table, and each display can run in its own selected language. The other GUIX resource types (colors, fonts, and pixelmaps) are also maintained by the GUIX Display component, since these resource types are specific to each display color format and color depth.

While you can manually create your application string table, most often the display string table is defined by the GUIX Studio application as part of your project resource file. The available languages are also defined in the resource header file. The display string table is a multi-column table of pointers to application strings. Each column of the string table represents one language supported by the application. If your application supports only one language, for example English, then your string table will have only one column. Still, you can add support for additional languages at any time without modifying your application software.

The active string table is assigned by calling the gx_display_string_table_set API function. This function is called automatically by the GUIX Studio generated startup code, but can also be called directly by the application to change the active string table.

The active language is assigned by calling the gx_display_active_language_set API function. This function determines which column of the display string table is active.

When this function is invoked, a GX_EVENT_LANGUAGE_CHANGE event is sent to all visible GUIX widgets, allowing them to update to display the newly active string data.

Widgets and application software resolve statically defined strings using string ID values and the gx_display_string_get_ext or gx_widget_string_get_ext API functions. These functions return the GX_STRING associated with a given string ID and the currently active language.

GUIX provides two strategies for bi-directional text support.

One option is to do bidi text reordering within the GUIX Studio application. Using this option GUIX Studio is responsible for generating bidi text to the output file in its display order. This solution has zero impact on the runtime performance and does not require any additions to the GUIX runtime library. To allow GUIX Studio to generate display order bidi text strings, you should select the Generate Bidi Text in Display Order checkbox in the GUIX Studio language configuration dialog:

With these options selected, the generated resource file will contain Bidi strings generated in display order, and no extra processing is required within the GUIX runtime library.

The second option is to do bidi text reordering at runtime. This option is supported for those applications that must handle bidi text string that are dynamically defined, and not generated by the GUIX Studio application. In this case, the GUIX runtime library is responsible for reordering the bidi text before drawing each text string. This solution has a runtime performance and memory impact. Sufficient dynamic memory must be available for bidi text reordering process. This solution requires that the conditional GX_DYNAMIC_BIDI_TEXT_SUPPORT be defined when building the GUIX library. Two API functions gx_system_bidi_text_enable and gx_system_bidi_text_disable are provided to enable/disable bidi text support at runtime.

You should not use both GX_DYNAMIC_BIDI_TEXT_SUPPORT and configure GUIX Studio to generate Bidi text in display order. You must select one strategy or the other for bidi text string handling.

Most of the development tools divide the application program image into five basic areas: instruction, constant, initialized data, uninitialized data, and the GUIX thread stack. The figure below demonstrates one possible layout of these memory areas:

It is important to understand that this only an example. The actual static memory layout is specific to the processor, development tools, underlying hardware, and the application itself.

The instruction area contains all of the program’s processor instructions. This area is often located in ROM.

The constant area contains various compiled constants, which in GUIX contains default settings and all application resources (images, strings, fonts, and colors). In addition, this area contains the "initial copy" of the initialized data area. During the compiler’s initialization process, this portion of the constant area is used to set up the global initialized data in RAM. The constant area is typically the largest and usually follows the instruction area and is often located in ROM.

GUIX pixelmaps and fonts typically require large amounts of constant data storage. These large static data areas are normally kept in ROM or FLASH.

The GUIX thread stack is defined within the uninitialized data area (as a global variable) in gx_system.h file as follows:

GX_THREAD_STACK_SIZE is defined in gx_port.h, but may be overridden by the application by defining this symbol in the gx_user.h header file or via project options or command line parameters. The stack size must be large enough to handle the worst case event handling and nested drawing calls.

As mentioned before, dynamic memory usage is under direct control of the application. Control blocks and memory associated with canvases, etc. can be placed anywhere in the target’s memory space. This is an important feature because it facilitates easy utilization of different types of physical memory — at run-time.

For example, suppose a target hardware environment has both fast memory and slow memory. If the application needs extra performance for drawing, the canvas memory can be explicitly placed in the high-speed memory area for best performance.

Several optional GUIX services and features require a runtime dynamic memory allocation mechanism, commonly referred to as a heap. These services and features are completely optional, and many GUIX applications do not use any heap and do not define a runtime memory allocation mechanism.

If you will be using services which require runtime memory allocation, you must install functions which GUIX will call when memory must be dynamically allocated or freed. You can implement these functions as you prefer, so that even in this case the location of the dynamic memory pool is under application control. To install support for dynamic memory allocation, the application should invoke the API service gx_system_memory_allocator_set during program startup to define your memory allocation and memory free services. Refer to the documentation of this API for a complete example.

GUIX services which require a runtime memory allocation and de-allocation service include:

For smaller applications, GUIX resources are usually compiled and statically linked as part of the application image, and binary resource installation is not required. Binary resources allow an application to install resources (fonts, images, languages) at runtime loaded from some storage location, such as a flash drive or a URL.

The runtime jpeg and png decoders are optional components. Most GUIX applications allow the GUIX Studio tool to pre-decode all required image files, and store them as proprietary GUIX Pixelmap data resources. These services are provided for completeness for those applications that require runtime conversion of jpeg and/or PNG images to pixelmap format.

GX_STYLE_TEXT_COPY allows the user to specify that a particular widget or widgets will keep it’s own private copy of dynamically assigned text. Using this option requires that the memory allocation mechanism be installed prior to use. If this style flag is not provided when a text type widget is created, the application must allocate static storage areas for all dynamically created and assigned text strings. Automatic variables should not be used in this case to hold runtime generated string data. If the GX_STYLE_TEXT_COPY style is enabled, automatic variables may be used to hold string data assigned to GUIX widgets, since each widget will create its own copy of the assigned text.

Pixelmap resize and rotation utility functions return the resulting translated pixelmap as a new pixelmap available to the application. Sufficient dynamic memory must be available to hold these runtime generated pixelmap data blocks if these services are used.

Finally, the control blocks for the GUIX screens and widgets can be statically or dynamically allocated. For smaller applications, it is common to create all application screens during program startup and use statically allocated control blocks. For large applications, it is common to create the screen and child widget controls dynamically on an as-needed bases. Dynamically allocated control blocks are specified by selecting the Runtime Allocate checkbox in the GUIX Studio properties view, or by passing in the style flag GX_STYLE_DYNAMICALLY_ALLOCATED when creating a widget via the standard API. Using dynamically allocated widget control blocks requires that memory allocation and deallocation services are defined as described above.

GUIX initialization is accomplished by the application calling the service gx_system_initialize, which may be called by the application from the ThreadX tx_application_define routine (initialization context) or from application threads. The gx_system_initialize function initializes all global GUIX data structures and creates the GUIX system mutex, event queue, timer, and thread. Once gx_system_initialize returns, the application can use GUIX.

The internal GUIX thread — created during initialization — is responsible for most of the processing in GUIX. The processing in this thread first completes any additional initialization required by the underlying display driver. Once this is complete, the GUIX thread enters a loop which first processes all events present in the GUIX event queue and then refreshes the screen if required. The screen refresh executes the necessary GUIX drawing functions, based on what is visible and has been marked as dirty meaning it needs to be redrawn. When there are no events and nothing left to refresh on the display, the GUIX thread will suspend, waiting for the next GUIX event to arrive.

The GUIX system component is by default configured to utilize the ThreadX real time operating system for services such as thread services, event queue services, and timer services. GUIX can easily be ported to other operating systems by using the preprocessor directive GX_DISABLE_THREADX_BINDING and re-building the GUIX library. This removes the ThreadX dependencies from the GUIX source code, and allows the application developer to implement the required operating system services using whatever RTOS is provided by the target system. Appendix F - GUIX RTOS Binding Services describes the services that need to be implemented to port GUIX to an operating system other than the ThreadX operating system.

The GUIX API is available from the GUIX thread context as well as other application threads. Application threads can interact with the GUIX thread by sending and receiving events, by access to shared variables, and through use of the GUIX API functions. GUIX uses an internal ThreadX mutex for multi-thread resource protection. In addition, GUIX prevents the internal structure of visible widgets from being modified once a screen refresh operation has begun. APIs which would modify the tree of visible objects are blocked while drawing operations are in progress, and released once the screen refresh is complete.

GUIX provides the application with periodic timers, which are often used for periodic update of data displayed in GUIX windows. This is accomplished via a ThreadX periodic timer, which is also used to perform GUIX system-level effects like screen fade in/out, etc.

The application can create timers and utilize the same timer facility that is used internally by GUIX. Of course the application can also directly create and use ThreadX timers if required. The advantage of the GUIX timers is that they are very easy to use and are pre-configured to work within the GUIX event-driven processing system.

To create and start a GUIX timer, the application should invoke the function gx_system_timer_start. The parameters to this function include a pointer to the calling widget, the timer ID (allowing one widget to start many timers), and the initial and reschedule timeout values. If the reschedule timeout value is 0, the timer will only run one time and will delete itself from the active timer list once it expires.

Once started, the GUIX timer will send GX_EVENT_TIMEOUT events to the timer owner, either once or periodically depending on the timer reschedule value. A GUIX timer can be stopped by calling the API function gx_system_timer_stop.

The GUIX system component holds configuration information related to pen speed tracking. GUIX internally generated GX_EVENT_VERTICAL_FLICK and GX_EVENT_HORIZONTAL_FLICK events based on the speed and distance of PEN_DOWN events generated by the touch input driver, if any. The application can configure the minimum distance and speed required to trigger these internally generated events using the gx_system_pen_configure API function.

The GUIX system component provides services related to the GUIX screen stack, which is an optional functionality supporting a virtual widget stack onto which screens can be pushed, popped, and retrieved at runtime by the application. The screen stack is useful for managing complex menu systems, wherein the route by which the user may arrive at various states in the menu system is varied. Returning to the previous state in the menu system can be easily done by first pushing the previous screen state, then displaying the new screen, and allowing the new screen to pop the previous state from the screen stack when the current screen is dismissed.

GUIX supports a clipboard for copying and pasting text during runtime execution. This support is provided by the GUIX System component.

GUIX maintains a list of dirty widgets, meaning widgets that are visible and need to be redrawn due to status changes or being made newly visible. This dirty list improves drawing performance by allowing GUIX to do one canvas refresh operation to reflect all current changes to the UI status, rather than doing a canvas refresh as each UI change is made. This dirty list is also maintained by the GUIX system component.

Applications often desire to execute multiple animation sequences, often in parallel. GUIX maintains a pool of animation control blocks from which the application can allocate and use. This frees the application from statically defining these control blocks and allows them to be reused at different times, rather than defining a unique animation control block for every animation that the application might define. The animation control block pool is also maintained by the GUIX system component.

The GUIX system error handler is intended to assist the application in finding internal system errors in GUIX that might be more difficult to determine from the API perspective. Whenever a system error occurs inside of GUIX the internal _gx_system_error_process function is called. This function saves the error code provided and increments the total number of system errors detected. The system error variables are defined as follows:

UINT _gx_system_last_error;

ULONG _gx_system_error_count;

If the GUIX application is behaving strangely, it is useful to look at the error count variable in the debugger. If it is set, a good way to troubleshoot the problem is to set a breakpoint in the _gx_system_error_process function and see when/where it is being called from.

A canvas object can be created during initialization or anytime during the execution of application threads. There is no limit on the number of canvas objects that can be created by an application. Most applications, however, will create only one canvas object for all GUIX drawing.

The characteristics of each canvas object are found in its control block GX_CANVAS and is defined in gx_api.h. The memory required for a canvas object is provided by the application and can be located anywhere in memory. However, it is most common to make the canvas object control block and the drawing area a global structure by defining them outside the scope of any function.

GUIX supports alpha-blending of foreground and background colors on many levels, including bitmap alpha channel which specifies a blending ratio per pixel, brush alpha which specifies the blending ratio for a brush at 16 bpp and higher color depths, and canvas alpha which specifies the blending ratio for an overlay canvas.

The alpha value of a canvas is used when there are multiple canvases which are composited together for display within the frame buffer. If the canvas Z-order is such that a canvas is above other canvases, then the canvas alpha value can be set to blend the canvas with those that lie behind. Rapidly modifying the alpha value of a canvas is used to provide "fade in" screen transition effects, but the canvas alpha can be used in many ways.

If a canvas is bound to a hardware graphics layer using gx_canvas_hardware_layer_bind(), GUIX will attempt to implement canvas alpha blending utilizing hardware support, minimizing the software overhead associated with blending an overlay canvas.

Alpha values range from 0 through 255, where a value of 0 means the pixel is fully transparent and values greater than 0 are increasing less transparent canvas alpha value can only be supported for screen drivers running at 16-bpp and higher unless hardware assistance for canvas blending is provided.

A canvas can be offset within the visible frame buffer by invoking the gx_canvas_offset_set API service. Canvas offsets are usually used to implement sprite animations. If a canvas is bound to a hardware graphics layer by invoking the gx_canvas_hardware_layer_bind API function, GUIX will attempt to implement canvas offset changes utilizing hardware support, minimizing the software overhead associated with shifting the canvas position.

The GUIX canvas component provides a full drawing API to the application. Before the drawing APIs such as gx_canvas_line_draw or gx_canvas_pixelmap_draw can be invoked, the target canvas must be opened for drawing by invoking the gx_canvas_drawing_initiate API function. This function prepares a canvas for drawing and creates a drawing context.

The drawing APIs that render to the canvas, such as gx_canvas_line_draw or gx_canvas_text_draw, use parameters found in the current drawing context brush to define the line style, width, and colors. These brush parameters are modified by calling the gx_context_brush_define, gx_context_brush_set, gx_context_brush_style_set, and similar API functions after a drawing context has been established by calling gx_canvas_drawing_initiate.

When GUIX invokes the window and widget drawing functions as part of a deferred canvas refresh operation, the target canvas is opened for drawing prior to calling the widget drawing function(s). Therefore the standard widget drawing functions are not required to open the target canvas, this has been done for them.

In some cases the application may want to force immediate drawing to a canvas. In this case, the application can perform the following steps.

There are several principal drawing primitives that are required by GUIX to draw all the visual elements on the screen. These drawing APIs can also be invoked by application software, usually as part of a custom widget drawing function. These GUIX canvas drawing APIs perform parameter validation and clipping, and then pass the clipped drawing coordinates down to the display driver for hardware and color-format specific drawing implementations. These drawing API functions are defined as follows.

The drawing API is invoked via the GUIX Canvas API, and all drawing is done using gx_canvas_* API functions. Drawing is done using the current brush in the current drawing context. Any of the shape drawing functions above can be outlined, solid color filled, or pixelmap filled as defined by the current brush. To modify the shape outline width, color, or fill, use the gx_context_brush_* API functions to define the brush within the current drawing context.

The above application level drawing APIs don’t do actual drawing to the canvas, but instead verify the caller’s parameters before invoking the display driver level drawing function. The driver level drawing function actually writes pixel data into the canvas memory.

GUIX provides stock or generic display driver drawing functions for various color depths, including 1, 2, 4, 8, 16, 24, and 32 bits per pixel (bpp). In some cases, the default software drawing implementation is replaced by hardware-accelerated implementations for those hardware targets that provide a 2D drawing accelerator.

GUIX supports color depths up to 32-bpp as well as monochrome and grayscale. The type of color depth support largely determined by the capabilities of the underlying physical display and also has an impact on how much memory is required for the canvas drawing area. The following is a list of color depth support along with a brief description of the variations within that color depth.

GUIX supports drawing a mouse cursor on any desired canvas. The mouse cursor can be drawing in software or might be supported by hardware cursor overlay. In either case, the API provided to the application related to mouse cursor support is the same whether using software or hardware mouse cursor drawing.

GUIX mouse support is only enabled if the #define GX_MOUSE_SUPPORT is defined in the gx_user.h header file before building the GUIX library.

The application must define the mouse cursor and hotspot using the gx_canvas_mouse_define API function. This API accepts a pointer to the canvas on which the cursor image should be drawn, and a pointer to a GX_MOUSE_CURSOR_INFO structure, which defines the mouse cursor image and hotspot of the mouse image relative the image top-left corner.

A display object can be created during initialization or anytime during the execution of application threads. Typically an application creates one display object to manage each physical screen. If you have used GUIX Studio to define your application and the physical displays available, you will use the gx_studio_display_configure API function to create and initialize each of your displays.

The characteristics of each display object are found in its control block GX_DISPLAY and are defined in gx_api.h. The memory required for a display object is provided by the application and can be located anywhere in memory. However, it is most common to make the display control block a global structure by defining it outside the scope of any function.

Resources are UI components that are needed by the application, but they are not application code. Resources are application data and are usually statically defined. Resource types include pixelmaps, fonts, colors, and strings. These resources can be changed at any time, usually without changing any application software. It is important to keep the storage of and references to resources separated from the application software to allow changing UI appearance without changing application code since changes to the application software usually require the associated re-testing and verification of that software.

The GUIX display module provides resource management facilities for all resources that are dependent on the color depth and format of the display. These facilities include maintaining the active pixelmap table, active font table, and active color table. The string table resource is maintained by the GUIX system module, since string resources do not normally need to be changed based on color depth and format.

The application software references resources by their resource ID, which is an index into the corresponding resource table. This allows the table to be changed, for example the color table might be changed when a product changes from "day mode" to "night mode", but the color ID values to remain the same.

Your application resources are written to a resource file (or set of resource files) by the GUIX Studio application. Default colors, pixelmaps, and fonts are provided automatically when you create a new GUIX Studio project, but these defaults are easily replaced as you define the look and feel of your application.

It is important to note that Resource IDs for colors, fonts, and pixelmaps cannot be resolved to their actual color, font, or pixelmap values until the active Display component is known. Since the GUIX architecture supports multiple active displays, Resource IDs can only be resolved to resource values when a widget and its associated Resource ID can be resolved to a specific display. This property is known as dynamic binding. The Resource ID for a property such as a text color, for example the resource ID GX_COLOR_ID_TEXT, might resolve to a 16-bit R:G:B value for white when used on one display, but the same color ID might resolve to a monochrome black color value when used on another display.

In practice this dynamic binding of Resources IDs to resource values means that application software and GUIX internal components should most often only resolve Resource IDs to resource values within an active drawing context. An active drawing context specifies the currently active display, which allows GUIX to resolve each Resource ID to a specific resource value. If the application software is required to find a specific resource value outside of a drawing context, this can also be done for visible widgets. Visible widgets are linked to a root window which can also be used to resolve the active canvas and display for that widget.

If a widget has been created but not yet displayed (i.e., has not been linked to any root window or other visible parent), any resource IDs associated with that widget cannot be resolved to a specific resource value other than by directly indexing into the resource table assigned to a specific display. This direct access to a specific resource table can safely be done by the application software, but is never done in the internal GUIX library software.

The GUIX display component also provides default definitions for various widget attributes. Unless otherwise specified by the application, widgets/windows are created with these system attributes. These system attributes are mainly composed of fonts, colors, and bitmaps maintained in the system resource tables. Additional attributes for default scrollbar appearance are also maintained by the GUIX display component.

The default color settings are defined by the color table assigned to each display and the pre-defined default color IDs. These default color IDs include the following.

These color ID values are mapped to a specific color value as defined by the color table assigned to each display. These defaults can be changed as a group for one display by calling the gx_display_color_table_set API function. If you are using GUIX Studio, the display color table is automatically initialized when your application calls the gx_studio_display_configure function.

The GUIX display component also maintains a default font table. The default font table defines the font used by each widget type unless specifically specified by the application. The pre-defined display font table IDs include the following values.

The font ID used by any text type widget can be re-assigned by using the gx__font_set API provided for each text-related widget type. The entire font table can be re-assigned by calling the gx_display_font_table_set API function.

GUIX Display also maintains default scrollbar appearance settings for that display. These settings are defined by the GX_SCROLLBAR_APPEARANCE structure which is defined below. GUIX Display maintains one scrollbar appearance structure for vertical scrollbars and a second structure for horizontal scroll bars. The application can modify the default scrollbar appearance for any display by initializing a GX_SCROLLBAR_APPEARANCE structure and invoking the API function gx_display_scroll_appearance_set.

| GX_SCROLLBAR_APPEARANCE Structure Member | Description | | — | — | | gx_scroll_width | Width of a vertical scrollbar or height of a horizontal scrollbar, in pixels. | | gx_scroll_thumb_width | Width of the elevator and end buttons, in pixels. | | gx_scroll_thumb_travel_max | Offset from the end of scroll bar to maximum thumb button travel point. | | gx_scroll_fill_pixelmap | Pixelmap used to fill scroll background. | | gx_scroll_thumb_pixelmap | Pixelmap used to draw scroll thumb button. | | gx_scroll_up_pixelmap | Pixelmap used to draw scroll up button. | | gx_scroll_down_pixelmap | Pixelmap used to draw scroll down button. | | gx_scroll_fill_color | Color ID of color used to fill scrollbar background. | | gx_scroll_button_color | Color ID of color used to fill scrollbar thumb button. |

In addition to these default settings for fonts, color, and styles, the application may specify any of the parameters on a case by case basis as desired using API provided by each widget type.

Skinning allows GUIX widgets and windows to easily change their base appearance, i.e., changing the "skin" in one place will change the base appearance of all associated widgets and windows.

Re-skinning your GUIX application requires that you supply a new color, font and or pixelmap table to the GUIX Display resource tables. Since all GUIX widgets refer to their color, bitmap, or font by resource ID, providing a new resource table automatically causes all GUIX widgets to begin using your new colors and pixelmaps when they draw themselves to the desired display.

A new set of fonts, colors, and pixelmaps that are designed to work together to provide an attractive appearance is called a theme. A theme defines a set of resource tables and the size of each resource table. Any number of themes can be defined for any display using the GUIX Studio application. You must pass the starting theme index to the GUIX Studio generated function gx_studio_display_configure, which installs the initial theme into the created display. The active theme for any display can be changed at any time by calling the function gx_display_theme_install.

For each visible canvas created by an application, the application must also create one Root Window for that canvas. This special window basically acts as a container for all the top-level application windows and widgets. The root window draws the canvas background, and since the root window is derived from the GX_WINDOW class the root window can also have wallpaper. To change the background color of your display or canvas, you simply change the fill color of the root window attached to that canvas.

If you use the GUIX Studio generated function named gx_studio_display_configure to configure your displays, then the canvas and root window for each display are created for you as part of this initialization function.

Anti-Aliasing is an optional feature in GUIX that is used to smooth lines, curves, and fonts. Anti-aliasing is only supported when running with a display driver utilizing 16-bpp or higher color depth.

Anti-aliased line drawing is enabled by setting the GX_BRUSH_ALIAS flash in the active brush. This applies to lines drawn directly as well as to lines drawn as the border of a polygon or circle.

Anti-aliased text drawing is enabled by using an anti-aliased font which is produced by the GUIX studio application. You specify whether a font should be generated as antialiased or binary when you create the font. Anti-aliased fonts in GUIX utilize 16 levels of transparency for each pixel.

Clipping is supported internally by the GUIX display component, and at the window and widget layers by the parent-child architecture maintained by GUIX widgets. No window or widget is ever allowed to draw outside of that widget’s area, and a widget is never allowed to draw outside of the area of that widget’s parent.

This also prevents widgets from drawing at pixel coordinates that lay outside of the canvas memory which likely lead to memory corruption or a system failure. Widgets are not allowed to draw outside of the widget’s area, the widget’s parent area, or beyond the canvas extent.

In addition, widgets can only draw to areas that have previously been marked as dirty. This prevents an entire window being drawn, for example, when only a corner of the window has been revealed. Only the portion of the window that actually needs to be refreshed is marked as dirty, and so the window drawing function only truly refreshes pixels in the dirty area.

The GUIX display component enforces these clipping algorithms before invoking the driver level drawing functions.

GUIX always maintains a set of views for each root window and each child window of the root window. Views are a dynamic, run-time determined clipping area that changes as window position and Z-order are modified. GUIX uses views to prevent a window or widget in the background from drawing on top of a window or widget in the foreground. Views enforce Z-order discipline. In addition, views are important for efficiency in that they prevent a window in the background from drawing to any area of the canvas that cannot be seen. If a window is completely covered by another window, the covered window will not be allowed to draw to the canvas at all, even if it is attempting to do so.

GUIX display drivers are responsible for all interaction with the underlying physical screen. The display drivers have three basic functions: initialization, drawing, and frame buffer display. Initialization is responsible for preparing the physical display hardware, informing GUIX of the properties of the physical display hardware, and for informing GUIX which specific drawing functions should be used. The main display driver initialization is called from the GUIX gx_display_create function. In addition, the GUIX thread will also call a secondary display driver initialization from the thread context. This secondary display driver is only needed if the driver requires RTOS services during its initialization, e.g., device interrupts or tx_thread_sleep requests for delay between steps in the initialization process.

Once initialization is complete, the display driver is responsible for any direct drawing that can be done in the physical display hardware. Finally, the display driver is responsible for displaying the frame buffer.

A widget object can be created during initialization or anytime during the execution of application threads. There is no limit on the number of widget objects that can be created by an application. There is also no limit on the number of children any widget may have, within the memory limits of your target hardware.

Each widget type has its own create function, such as gx_button_create or gx_prompt_create. The first three parameters to these functions are always the same, namely a pointer to the widget control structure, a string pointer to the widget name, and a pointer to the widget’s parent. Each create function may have any number of additional parameters depending on the requirements of that particular widget type.

The characteristics of each widget object are found in its control block GX_WIDGET and are defined in gx_api.h. The memory required for a widget object is provided by the application and can be located anywhere in memory. However, it is most common to make the widget object control block a global structure by defining it outside the scope of any function. If you are using GUIX Studio, your widget control blocks can be statically allocated within your Studio generated specifications file, or they can be dynamically allocated by your application.

If you are using dynamic control block allocation, you will need to define two functions that GUIX will use to allocate and free the memory required for your widget control blocks. Your functions for memory management are passed to the GUIX system component via the gx_system_memory_allocator_set API function. This function allows you to pass two function pointers into GUIX: the first is a pointer to a memory allocation function, and the second is a pointer to a memory free function. Most often, you will implement these functions using ThreadX byte pools, but the design of GUIX allows you to implement dynamic memory management in whatever way you prefer.

Dynamic widget allocation is most often employed within your Studio generated application specifications file, when you select the "dynamically allocated" option in the Studio widget properties field. However, you can also use dynamic control block allocation within your application. If you use dynamic control block allocation within your application, you should invoke the gx_widget_allocate API function to allocate the widget control block. Next, when you create the widget, make certain you pass the GX_WIDGET_STYLE_DYNAMICALLY_ALLOCATED style flag (along with any other needed style flags) to the widget create function. This flag is used to mark the widget as being dynamically allocated in the widget status field. When and if the widget is later deleted using gx_widget_delete, GUIX will check this status field and automatically call your memory de-allocator function to ensure there are no memory leaks.

GUIX provides a rich, fully functional set of built-in widgets. As mentioned previously, all specialized widgets are derived from the base widget. Following is a list of the built-in widgets in GUIX:

GX_TYPE_WIDGET

GX_TYPE_BUTTON

GX_TYPE_TEXT_BUTTON

GX_TYPE_MULTI_LINE_TEXT_BUTTON

GX_TYPE_RADIO_BUTTON

GX_TYPE_CHECKBOX

GX_TYPE_PIXELMAP_BUTTON

GX_TYPE_ICON_BUTTON

GX_TYPE_ICON

GX_TYPE_SPRITE

GX_TYPE_SLIDER

GX_TYPE_PIXELMAP_SLIDER

GX_TYPE_VERTICAL_SCROLL

GX_TYPE_HORIZONTAL_SCROLL

GX_TYPE_PROGRESS_BAR

GX_TYPE_PROMPT

GX_TYPE_NUMERIC_PROMPT

GX_TYPE_PIXELMAP_PROMPT

GX_TYPE_NUMERIC_PIXELMAP_PROMPT

GX_TYPE_SINGLE_LINE_TEXT_INPUT

GX_TYPE_MULTI_LINE_TEXT_VIEW

GX_TYPE_MULTI_LINE_TEXT_INPUT

GX_TYPE_WINDOW

GX_TYPE_ROOT_WINDOW

GX_TYPE_VERTICAL_LIST

GX_TYPE_HORIZONTAL_LIST

GX_TYPE_POPUP_LIST

GX_TYPE_DROP_LIST

GX_TYPE_LINE_CHART

GX_TYPE_DIALOG

GX_TYPE_KEYBOARD

GX_TYPE_SCROLL_WHEEL

GX_TYPE_TEXT_SCROLL_WHEEL

GX_TYPE_STRING_SCROLL_WHEEL

GX_TYPE_NUMERIC_SCROLL_WHEEL

GX_TYPE_CIRCULAR_GAUGE

GX_TYPE_RADIAL_PROGRESS_BAR

GX_TYPE_RADIAL_SLIDER

GX_TYPE_MENU_LIST

GX_TYPE_MENU

GX_TYPE_ACCORDION_MENU

GX_TYPE_TREE_VIEW

Widget styles consist of things like border properties (raised, recessed, thin, thick, or no boarder at all) as well as properties for specific widget types, as listed previously. The widget style flags offer the simplest method for modifying the appearance of any widget. The initial widget style is always a parameter passed to the widget type specific create function.

Widgets draw themselves using colors defined in the system color table. Color IDs are defined for canvas background, default widget fill color, button fill color, text widget fill color, window fill color, and several other default color values. In addition, GX_WINDOW objects support displaying a bitmap or wallpaper as the window client is filled.

The simplest method of changing the default color scheme is to use GUIX Studio and create or define a color scheme that meets your requirements. You can also define your color scheme manually by creating an array of GX_COLOR values and invoking the gx_system_color_table_set API function.

GUIX events are requests made to one or more widgets to perform a particular action and notifications to notify widgets of user input and internal system status changes. For example, when a widget gains focus, the GX_EVENT_FOCUS_GAINED is sent to the widget via the gx_system_event_send API service.

Events are passed through the GUIX event queue, and each event is an instance of the GX_EVENT data structure. The GX_EVENT data structure is defined in gx_api.h, however the most important fields of the structure are the gx_event_type, gx_event_sender, gx_event_target, and gx_event_payload.

The gx_event_type field is used to identify the particular event class. The event type indicates if this is, for example, a GX_EVENT_PEN_DOWN event or a GX_EVENT_TIMER event. The gx_event_payload is a union of various data fields, and they are not all valid for every event type. You use the event type field first, before examining the other event data fields.

The gx_event_sender field contains the ID of the widget that generated the event if the event is a child-widget notification.

The gx_event_target field can be used to route user-defined events to a particular window or widget. If you want to send an event to a particular window, you should give the window a unique ID value (so that it can be positively identified), and when building the event place the window ID value in the gx_event_target field. If you don’t know the target ID or if you just want the event to be routed to the widget that has input focus, make sure to set the gx_event_target field to 0.

Finally, the gx_event_payload field is a union of various data types. For GX_EVENT_PEN_DOWN and GX_EVENT_PEN_UP events, the gx_event_pointdata field contains the x,y pixel coordinate the pen position. For timer events, the gx_event_timer_id field contains the ID of the expired timer. Other payload data fields are utilized for other event types. The complete list of pre-defined event types and their payload fields is defined in Appendix E - GUIX Event Descriptions.

The application can also add its own custom events, starting numerically after the constant GX_FIRST_APP_EVENT. All event numbers after this constant are reserved for the application’s use. Of course, the application’s widget event handler must have processing for such application events.

There is a default widget event processing function for each and every widget, named gx<widget-type>_event_process_. In most cases, the application won’t need to worry about the event handling of any given widget. However, in situations where the application requires custom or supplemental event processing, the application may override the default processing function with its own via the GUIX API gx_widget_event_process_set. This function overrides the default event processing function with the event function processing function specified in the API.

Event processing is called exclusively from the context of the internal GUIX system thread. In this way, the stack requirements to process the event handling only applies to the GUIX thread.

You can provide your own event processing function for any widget or window in the GUIX system. If you are creating your own custom widget type, you will normally install your custom event handler in the widget creation function. If you are just extending or modifying the operation of an existing widget or window, you can call the gx_widget_event_process_set API function after the widget or window has been created. You will almost always provide your own event handling for your top-level windows (also called Screens) in order to process events generated by your child controls. Processing event generated by the child controls of a screen is the main way you add functionality to your GUIX application.

As an example, suppose you define a top-level screen named "main_menu". This screen might be defined using GUIX Studio, or you might create this screen in your application code. If you define the screen within GUIX Studio, you simply type the name of your event handler in the Studio properties field for that screen, and the Studio generated specifications code will automatically install your event handler. In this case, we will call the custom event handler main_menu_event_handler and it should be coded like this:

In the example above, it is important to notice that for system events like GX_EVENT_SHOW (events generated internally to notify a widget of a status change), the application must pass those events to the base widget event processing function to insure that the normal processing occurs. The application can then add additional logic as desired. All events that are not handled by the application (the default case above) should also be passed to the base event processing function. Since this example was for a top-level screen based on GX_WINDOW, the default event processing function is gx_window_event_process.

All widget drawing is performed separately from the event handling. This is more efficient because drawing is usually expensive in terms of CPU cycles. By implementing a deferred drawing algorithm, all of the outstanding events and associated display changes can be completed before any drawing is done, thus eliminating wasted drawing. Similar to event processing, there is a default widget drawing function for most widgets, named gx<widget-type>_draw_, where xxx is the widget type. In most cases, the application won’t need to worry about the drawing function of any given widget. However, in situations where the application requires custom or supplemental drawing, the application may override the default drawing function with its own via the GUIX API gx_widget_draw_set. This function allows the application to provide its own customized drawing function for any widget. This further allows the application to define entire new widget types.

Widget drawing is called exclusively from the context of the internal GUIX system thread. In this way, the timing and stack requirements to perform the drawing only apply to the GUIX thread.

The drawing function for any widget is referenced through an indirect function pointer which is a member of the GX_WIDGET control block. If you use GUIX Studio to define your widget, you can install your own function pointer simply by typing the name of your function in the "Drawing Function" parameter of the widget properties, and Studio will install your function pointer for you when the widget is created. If you create the widget in your application code, you must use the gx_widget_draw_set API function to install your custom drawing function after the widget has been created.

For this example, let’s assume that you want to customize the appearance of a button. The button will look very much like a GX_TEXT_BUTTON, but we will add drawing a small green "LED_ON" bitmap in the middle-right portion of the button when the button is pressed, and small "LED_OFF" bitmap when the button is not pressed. We want to create a button that looks like the illustrations below.

custom button "on"

custom button "off"

In this case, we would write a button drawing function that looks something like the following.

A window object can be created during initialization or anytime during the execution of application threads. There is no limit on the number of window objects that can be created by an application. There is also no limit on the number of children any window may have.

The characteristics of each window object are found in its control block GX_WINDOW and are defined in gx_api.h. The memory required for a window object is provided by the application and can be located anywhere in memory. However, it is most common to make the window object control block a global structure by defining it outside the scope of any function.

GUIX requires what is called a root window for each canvas. The root window is borderless and has the same dimensions as the canvas to which it is attached. It is used primarily as a container for all first-level widgets and windows. The root window is typically created by the application via the API function gx_window_root_create, shortly after the creation of the screen and canvas. If you use the Studio generated function gx_studio_display_configure, the address of the root window can be returned in the location passed as the last parameter to this function.

A root window defaults to being un-moveable, and in the simplest case the root window is the size of the canvas. The root window in effect draws the display background, so to change the display background color or to display background wallpaper you would assign a color or wallpaper to the root window.

If a root window is moveable, it moves not by changing its position on the canvas as a child window would do, but by moving the canvas itself. This feature allows the GUIX root window to leverage hardware that supports multiple frame buffers with hardware offset registers.

Window backgrounds are either solid colors or bitmap images. There is a default window background at the system level which provides the default for the initial set of windows. Of course, any window background can be changed via the GUIX API.

To change the solid color background of a window, use the gx_widget_fill_color_set API. To assign a background wallpaper to a window, use the gx_window_wallpaper_set API.

GUIX supports standard window scrolling when area required to display the window children exceeds the current size of the window — horizontally and/or vertically. To enable scrolling, the application must create the desired scroll bars and attach them to the window.

The GUIX window component provides a default scrolling implementation based on the size of the window client area and the extent of the all child widgets. Applications can also provide their own scrolling implementation and interpretation by overriding the gx_window_scroll_info_get function for a particular window.

The default window event processing function differs from the GX_WIDGET event processing primarily in the handling of scrolling and sizing events. GX_WINDOW provided default handlers for scrolling and sizing events.

The application can also add its own custom events, starting numerically after the constant GX_FIRST_APP_EVENT. All event numbers after this constant are reserved for the application’s use. Of course, the application’s window event handler must have processing for such application events.

Just like all other widget types, there is a default window event processing function for every window, named gx_window_event_process. You will usually override this event handling function with your own event handler in the windows that you create. This is how you will respond to events and take action based on events generated by the window child controls.

It is important to remember to invoke the base gx_window_event_process function for GUIX system events if you override that event handler, to allow the default event handling to occur in addition to whatever action you are adding to the event handler. For example if you provide a custom handler for the GX_EVENT_SHOW event, and do not pass this event to gx_window_event_process, your window will never become visible. To provide a custom event handler for a window, use the gx_widget_event_process_set function to define the address of your event handler. This function overrides the default event processing function with the event function processing function specified in the API.

Event processing is called exclusively from the context of the internal GUIX system thread. In this way, the stack requirements to process the event handling only applies to the GUIX thread.