mirror of
https://github.com/eclipse-threadx/rtos-docs.git
synced 2026-10-06 12:59:07 +08:00
Initial commit
This commit is contained in:
Eric Wolz
@@ -0,0 +1,5 @@
|
||||
################################################################################
|
||||
# This .gitignore file was automatically created by Microsoft(R) Visual Studio.
|
||||
################################################################################
|
||||
|
||||
/.vs
|
||||
@@ -0,0 +1,17 @@
|
||||
The MIT License (MIT)
|
||||
Copyright (c) Microsoft Corporation
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
|
||||
associated documentation files (the "Software"), to deal in the Software without restriction,
|
||||
including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
|
||||
subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial
|
||||
portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
|
||||
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
||||
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
@@ -0,0 +1,174 @@
|
||||
# What is Eclipse ThreadX?
|
||||
|
||||
Eclipse ThreadX is a real time operating system (RTOS) for Internet of Things (IoT) and edge devices powered by microcontroller units (MCUs). Eclipse ThreadX is designed to support most highly constrained devices (battery powered and having less than 64 KB of flash memory).
|
||||
|
||||
Eclipse ThreadX provides an EAL4+ Common Criteria security certified environment, including full IP layer security via IPsec and socket layer security via TLS and DTLS. Our software crypto library has achieved FIPS 140-2 certification. We also leverage hardware cryptographic capabilities, memory protection via ThreadX MODULES, and support for ARM's TrustZone ARMv8-M security features.
|
||||
|
||||
## Eclipse ThreadX resources
|
||||
|
||||
[Eclipse ThreadX repositories](https://github.com/azure-rtos/)
|
||||
|
||||
Documentation for components:
|
||||
|
||||
- [ThreadX](./rtos-docs/threadx/index.md)
|
||||
- [ThreadX Modules](./rtos-docs/threadx-modules/index.md)
|
||||
- [NetX Duo](./rtos-docs/netx-duo/index.md)
|
||||
- [GUIX](./rtos-docs/guix/index.md)
|
||||
- [FileX](./rtos-docs/filex/index.md)
|
||||
- [LevelX](./rtos-docs/levelx/index.md)
|
||||
- [USBX](./rtos-docs/usbx/index.md)
|
||||
- [TraceX](./rtos-docs/tracex/index.md)
|
||||
|
||||
Other resources:
|
||||
|
||||
- [Product Support Policy](./rtos-docs/general/lts.md)
|
||||
- [Security Updates](./rtos-docs/general/security-updates.md)
|
||||
|
||||
|
||||
## Components of Eclipse ThreadX
|
||||
|
||||
The Eclipse ThreadX platform is the collection of run-time solutions including ThreadX, NetX Duo, FileX, GUIX and USBX.
|
||||
|
||||
|
||||
|
||||
### ThreadX
|
||||
|
||||
ThreadX is an advanced Real-Time Operating System (RTOS) designed specifically for deeply embedded applications. Among the multiple benefits ThreadX provides are advanced scheduling facilities, message passing, interrupt management, and messaging services. ThreadX has many advanced features, including its picokernel architecture, preemption-threshold scheduling, event-chaining, and a rich set of system services.
|
||||
|
||||
### FileX
|
||||
|
||||
FileX is a high-performance FAT-compatible file system. It is fully integrated with ThreadX and is available for all supported processors. Like ThreadX, FileX is designed to have a small footprint and high performance, making it ideal for today's deeply embedded applications that require file operations. FileX supports most physical media, including RAM disk, USBX, SD CARD, and NAND/NOR flash memories via LevelX.
|
||||
|
||||
### GUIX
|
||||
|
||||
GUIX is a professional quality graphical user interface package, created to meet the needs of embedded systems developers. Unlike the alternatives, GUIX is small, fast, and easily ported to virtually any hardware configuration capable of supporting graphical output. GUIX also delivers exceptional visual appeal and an intuitive and powerful API for application-level user interface development.
|
||||
|
||||
### NetX Duo
|
||||
|
||||
NetX Duo is an advanced, Industrial Grade TCP/IP network stacks designed specifically for deeply embedded, real-time, and IoT applications. NetX Duo is a dual IPv4 and IPv6 network stack.
|
||||
|
||||
### USBX
|
||||
|
||||
USBX is a high-performance USB host, device, and On-The-Go (OTG) embedded stack. It is fully integrated with ThreadX and is available for all ThreadX supported processors. Like ThreadX, USBX is designed to have a small footprint and high performance, making it ideal for deeply embedded applications that require an interface with USB devices.
|
||||
|
||||
### Windows tools
|
||||
|
||||
GUIX Studio provides a complete GUI application design environment, facilitating the creation and maintenance of all graphical elements in the application's GUI. GUIX Studio automatically generates C code compatible with the GUIX library, ready to be compiled and run on the target.
|
||||
|
||||
TraceX is a host-based analysis tool that provides developers with a graphical view of real-time system events and enables them to visualize and better understand the behavior of their real-time systems.
|
||||
|
||||
## The Eclipse ThreadX Advantage
|
||||
|
||||
Eclipse ThreadX provides the following advantages over other real-time operating systems.
|
||||
|
||||
### Most deployed RTOS
|
||||
|
||||
Eclipse ThreadX has over 12 billion deployments worldwide. The popularity of Eclipse ThreadX is a testament to its reliability, quality, size, performance, advanced features, ease-of-use, and overall time-to-market advantages.
|
||||
> _"We have followed the growth trajectory of THREADX in the wireless and IoT markets since the company's founding, and are increasingly impressed by the widespread industry adoption of THREADX."_ – Chris Rommel, Executive Vice President, VDC Research
|
||||
|
||||
### Intuitive and consistent API design
|
||||
|
||||
- Intuitive and consistent API.
|
||||
- Noun-verb naming convention.
|
||||
- All APIs have leading prefix, such as \_tx\_\_ for ThreadX and \_fx\_\_ for FileX, to easily identify the Eclipse ThreadX component they belong to.
|
||||
- Functional consistency throughout the APIs. For example, all API functions that suspend have an optional timeout that functions in an identical manner.
|
||||
- Many APIs are directly available from application ISRs.
|
||||
- Optional user-notification callbacks for media and file operations.
|
||||
- Event-driven programming model (API).
|
||||
|
||||
### High efficiency
|
||||
|
||||
- Small code footprint.
|
||||
- Scalable code footprint based on the services used.
|
||||
- Fast execution. Eclipse ThreadX is designed for speed and has minimal internal function call layering to help achieve the fastest possible performance.
|
||||
|
||||
### Fastest time-to-market
|
||||
|
||||
Eclipse ThreadX is easy to install, learn, use, debug, verify, certify, and maintain. As a result, Eclipse ThreadX is one of the most popular real time operating systems for embedded IoT devices, including many SoCs from Broadcom, Gainspan, and so forth. Our consistent time-to-market advantage is built on:
|
||||
|
||||
- Complete source code availability.
|
||||
- Easy-to-use API.
|
||||
- Comprehensive and advanced feature set.
|
||||
- Quality documentation.
|
||||
|
||||
### One Simple License
|
||||
|
||||
There is no cost to use and test the source code and no cost for production licenses when deployed to pre-licensed devices, all other devices need a license.
|
||||
|
||||
### Full, highest-quality source code
|
||||
|
||||
Throughout the years, Eclipse ThreadX source code has set the bar in quality and ease of understanding. In addition, the convention of having one function per file provides for easy source navigation.
|
||||
|
||||
### Pre-certified by TÜV and UL to many safety standards
|
||||
|
||||
Eclipse ThreadX has been certified by SGS-TÜV Saar for use in safety-critical systems, according to IEC-61508 SIL 4. The certification confirms that Eclipse ThreadX can be used in the development of safety-related software for the highest safety integrity levels of IEC-61508 for the "Functional Safety of electrical, electronic, and programmable electronic safety-related systems." SGS-TUV Saar, formed through a joint venture of Germany's SGS-Group and TUV Saarland, has become the leading accredited, independent company for testing, auditing, verifying, and certifying embedded software for safety-related systems worldwide.
|
||||
|
||||
|
||||
|
||||
Eclipse ThreadX has been recognized by UL for compliance with UL 60730-1 Annex H, CSA E60730-1 Annex H, IEC 60730-1 Annex H, UL 60335-1 Annex R, IEC 60335-1 Annex R, and UL 1998 safety standards for software in programmable components. UL is a global, independent, safety-science company with more than a century of expertise innovating safety solutions, ranging from the public adoption of electricity to breakthroughs in sustainability, renewable energy, and nanotechnology.
|
||||
|
||||
|
||||
|
||||
Artifacts (Certificate, Safety Manual, Test Report, etc.) associated with the TUV and UL certifications are available to license.
|
||||
|
||||
In cases where the application needs additional certification, a certification service is available through Eclipse Foundation for providing turn-key certification to various standards using the actual hardware platform and even covering the application code. Contact us for more details on our certification service.
|
||||
|
||||
### EAL4+ Common Criteria security certification
|
||||
|
||||
ThreadX has achieved EAL4+ Common Criteria security certification. The Target of Evaluation (TOE) covers ThreadX, NetX Duo, NetX Secure TLS, and NetX MQTT. This represents the most typical IoT protocols required by deeply embedded sensors, devices, edge routers, and gateways.
|
||||
|
||||
|
||||
|
||||
The IT Security Evaluation Facility used for the Eclipse ThreadX SC security certification is Brightsight BV and the Certification Authority is SERTIT.
|
||||
|
||||
### FIPS 140-2 Validated
|
||||
|
||||
Eclipse ThreadX Crypto libraries have achieved Federal Information Processing Standardization 140-2 (FIPS 140-2) Certification for software, which specifies requirements for cryptography modules. FIPS 140-2 requires all federal government agencies and departments that use cryptographic-based security to meet specific standards related to encryption strength and capabilities. These cryptographic-based security standards are also recognized in Canada and the European Union.
|
||||
|
||||
The Information Security evaluation lab used for Eclipse ThreadX Crypto libraries was atsec and the certification authority is [The National Institute of Standards and Technology (NIST)](https://csrc.nist.gov/projects/cryptographic-module-validation-program/Certificate/3394).
|
||||
|
||||
### Supports most popular architectures
|
||||
|
||||
Eclipse ThreadX works on most popular 32/64-bit microprocessors, out-of-the-box, fully tested and fully supported, including the following advanced architectures:
|
||||
|
||||
- **Analog Devices**: SHARC, Blackfin, CM4xx
|
||||
|
||||
- **Andes Core**: RISC-V
|
||||
|
||||
- **Ambiqmicro**: Apollo MCUs
|
||||
|
||||
- **ARM**: ARM7, ARM9, ARM11, Cortex-M0/M3/M4/M7/A15/A5/A7/A8/A9/A5x 64-bi/A7x 64-bit/R4/R5, TrustZone ARMv8-M
|
||||
|
||||
- **Cadence**: Xtensa, Diamond
|
||||
|
||||
- **CEVA**: PSoC, PSoC 4, PSoC 5, PSoC 6, FM0+, FM3, MF4, WICED WiFi
|
||||
|
||||
- **Cypress**: RISC-V
|
||||
|
||||
- **EnSilica**: eSi-RISC
|
||||
|
||||
- **Infineon**: XMC1000, XMC4000, TriCore
|
||||
|
||||
- **Intel; Intel FPGA**: x36/Pentium, XScale, NIOS II, Cyclone, Arria 10
|
||||
|
||||
- **Microchip**: AVR32, ARM7, ARM9, Cortex-M3/M4/M7, SAM3/4/7/9/A/C/D/E/G/L/SV, PIC24/PIC32
|
||||
|
||||
- **Microsemi**: RISC-V
|
||||
|
||||
- **NXP**: i.MX RT10xx and RT116x/7x series crossover MCUs, LPC5500 series
|
||||
|
||||
- **Renesas**: SH, HS, V850, RX, RZ, Synergy
|
||||
|
||||
- **Silicon Labs**: EFM32
|
||||
|
||||
- **Synopsys**: ARC 600, 700, ARC EM, ARC HS
|
||||
|
||||
- **ST**: STM32, ARM7, ARM9, Cortex-M3/M4/M7
|
||||
|
||||
- **Tl**: C5xxx, C6xxx, Stellaris, Sitara, Tiva-C
|
||||
|
||||
- **Wave Computing**: MIPS32 4K, 24 K, 34 K, 1004 K, MIPS64 5K, microAptiv, interAptiv, proAptiv, M-Class
|
||||
|
||||
- **Xilinx**: MicroBlaze, PowerPC 405, ZYNQ, ZYNQ UltraSCALE
|
||||
|
||||
_All timing and size figures listed are estimates and may be different on your development platform._
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: FileX user guide
|
||||
description: This guide contains comprehensive information about FileX, the high-performance real-time file system from Eclipse Foundation.
|
||||
---
|
||||
|
||||
# About This FileX User Guide
|
||||
|
||||
This guide contains comprehensive information about FileX, the high-performance, real-time embedded file system from Eclipse Foundation. To gain the most from this guide, you should be familiar with standard real-time operating system functions, FAT file system services, and the C programming language.
|
||||
|
||||
## Organization
|
||||
|
||||
[Chapter 1](chapter1.md) - Introduces FileX
|
||||
|
||||
[Chapter 2](chapter2.md) - Gives the basic steps to install and use FileX with your ThreadX application
|
||||
|
||||
[Chapter 3](chapter3.md) - Provides a functional overview of the FileX system and basic information about FAT file system formats
|
||||
|
||||
[Chapter 4](chapter4.md) - Details the application's interface to FileX
|
||||
|
||||
[Chapter 5](chapter5.md) - Describes the supplied FileX RAM driver and how to write your own custom FileX drivers
|
||||
|
||||
[Chapter 6](chapter6.md) - Describes the FileX Fault Tolerant Module
|
||||
|
||||
[Appendix A](appendix-a.md) - FileX Services
|
||||
|
||||
[Appendix B](appendix-b.md) - FileX Constants
|
||||
|
||||
[Appendix C](appendix-c.md) - FileX Data Types
|
||||
|
||||
[Appendix D](appendix-d.md) - ASCII Chart
|
||||
|
||||
## Guide Conventions
|
||||
|
||||
*Italics* - Typeface denotes book titles, emphasizes important words, and indicates variables.
|
||||
|
||||
**Boldface** - Typeface denotes file names,
|
||||
key words, and further emphasizes important words and variables.
|
||||
|
||||
> **Note:** Information symbols draw attention to important or additional information that could affect performance or function.
|
||||
|
||||
> **Important:** Warning symbols draw attention to situations that developers should avoid because they could cause fatal errors.
|
||||
|
||||
## FileX Data Types
|
||||
|
||||
In addition to the custom FileX control structure data types, there is a series of special data types that are used in FileX service call interfaces. These special data types map directly to data types of the underlying C compiler. This is done to ensure portability between different C compilers. The exact implementation is inherited from ThreadX and can be found in the tx_port.h file included in the ThreadX distribution.
|
||||
|
||||
The following is a list of FileX service call data types and their associated meanings.
|
||||
|
||||
| Type | Description |
|
||||
|---|---|
|
||||
| **UINT** | Basic unsigned integer. This type must support 8-bit unsigned data; however, it is mapped to the most convenient unsigned data type. |
|
||||
| **ULONG** | Unsigned long type. This type must support 32-bit unsigned data. |
|
||||
| **VOID** | Almost always equivalent to the compiler's void type. |
|
||||
| **CHAR** | Most often a standard 8-bit character type. |
|
||||
| **ULONG64** | 64-bit unsigned integer data type. |
|
||||
|
||||
Additional data types are used within the FileX source. They are located in either the ***tx_port.h*** or ***fx_port.h*** files.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
For troubleshooting, be sure to collect the following information.
|
||||
|
||||
1. A detailed description of the problem, including frequency of occurrence and whether it can be reliably reproduced.
|
||||
2. A detailed description of any changes to the application and/or FileX that preceded the problem.
|
||||
3. The contents of the _tx_version_id and
|
||||
_fx_version_id strings found in the ***tx_port.h*** and ***fx_port.h*** files of your distribution. These strings will provide valuable information regarding your run-time environment.
|
||||
4. The contents in RAM of the following **ULONG** variables. These variables will give information on how your ThreadX and FileX libraries were built:
|
||||
|
||||
**_tx_build_options**
|
||||
|
||||
**_fx_system_build_options1**
|
||||
|
||||
**_fx_system_build_options2**
|
||||
|
||||
**_fx_system_build_options3**
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
title: Appendix A - FileX services
|
||||
description: Learn about the FileX Services.
|
||||
---
|
||||
|
||||
# Appendix A - FileX services
|
||||
|
||||
## System Services
|
||||
|
||||
```c
|
||||
UINT fx_system_date_get(UINT *year, UINT *month, UINT *day);
|
||||
UINT fx_system_date_set(UINT year, UINT month, UINT day);
|
||||
UINT fx_system_time_get(UINT *hour, UINT *minute, UINT *second);
|
||||
UINT fx_system_time_set(UINT hour, UINT minute, UINT second);
|
||||
VOID fx_system_initialize(VOID);
|
||||
```
|
||||
|
||||
## Media Services
|
||||
|
||||
```c
|
||||
UINT fx_media_abort(FX_MEDIA *media_ptr);
|
||||
UINT fx_media_cache_invalidate(FX_MEDIA *media_ptr);
|
||||
UINT fx_media_check(FX_MEDIA *media_ptr, UCHAR *scratch_memory_ptr,
|
||||
ULONG scratch_memory_size, ULONG error_correction_option,
|
||||
ULONG *errors_detected_ptr);
|
||||
|
||||
UINT fx_media_close(FX_MEDIA *media_ptr);
|
||||
UINT fx_media_close_notify_set(FX_MEDIA *media_ptr, VOID (*media_close_notify)(FX_MEDIA *media));
|
||||
UINT fx_media_exFAT_format(FX_MEDIA *media_ptr, VOID (*driver)(FX_MEDIA *media),
|
||||
VOID *driver_info_ptr, UCHAR *memory_ptr,
|
||||
UINT memory_size, CHAR *volume_name,
|
||||
UINT number_of_fats, ULONG64 hidden_sectors,
|
||||
ULONG64 total_sectors, UINT bytes_per_sector,
|
||||
UINT sectors_per_cluster, UINT volume_serial_number,
|
||||
UINT boundary_unit);
|
||||
UINT fx_media_extended_space_available(FX_MEDIA *media_ptr, ULONG64 *available_bytes_ptr);
|
||||
UINT fx_media_flush(FX_MEDIA *media_ptr);
|
||||
UINT fx_media_format(FX_MEDIA *media_ptr, VOID (*driver)(FX_MEDIA *media),
|
||||
VOID *driver_info_ptr, UCHAR *memory_ptr,
|
||||
UINT memory_size, CHAR *volume_name,
|
||||
UINT number_of_fats, UINT directory_entries,
|
||||
UINT hidden_sectors, ULONG total_sectors,
|
||||
UINT bytes_per_sector, UINT sectors_per_cluster,
|
||||
UINT heads, UINT sectors_per_track);
|
||||
|
||||
UINT fx_media_open(FX_MEDIA *media_ptr, CHAR *media_name,
|
||||
VOID (*media_driver)(FX_MEDIA *),
|
||||
VOID *driver_info_ptr, VOID *memory_ptr,
|
||||
ULONG memory_size);
|
||||
|
||||
UINT fx_media_open_notify_set(FX_MEDIA *media_ptr, VOID (*media_open_notify)(FX_MEDIA *media));
|
||||
|
||||
UINT fx_media_read(FX_MEDIA *media_ptr, ULONG logical_sector, VOID *buffer_ptr);
|
||||
|
||||
UINT fx_media_space_available(FX_MEDIA *media_ptr, ULONG *available_bytes_ptr);
|
||||
UINT fx_media_volume_get(FX_MEDIA *media_ptr, CHAR *volume_name, UINT volume_source);
|
||||
|
||||
UINT fx_media_volume_get_extended(FX_MEDIA *media_ptr, CHAR *volume_name,
|
||||
UINT volume_name_buffer_length, UINT volume_source);
|
||||
|
||||
UINT fx_media_volume_set(FX_MEDIA *media_ptr, CHAR *volume_name);
|
||||
UINT fx_media_write(FX_MEDIA *media_ptr, ULONG logical_sector, VOID *buffer_ptr);
|
||||
|
||||
```
|
||||
|
||||
## Directory Services
|
||||
|
||||
```c
|
||||
UINT fx_directory_attributes_read(FX_MEDIA *media_ptr, CHAR *directory_name,
|
||||
UINT *attributes_ptr);
|
||||
|
||||
UINT fx_directory_attributes_set(FX_MEDIA *media_ptr, CHAR *directory_name,
|
||||
UINT attributes);
|
||||
|
||||
UINT fx_directory_create(FX_MEDIA *media_ptr, CHAR *directory_name);
|
||||
UINT fx_directory_default_get(FX_MEDIA *media_ptr, CHAR **return_path_name);
|
||||
UINT fx_directory_default_set(FX_MEDIA *media_ptr, CHAR *new_path_name);
|
||||
UINT fx_directory_delete(FX_MEDIA *media_ptr, CHAR *directory_name);
|
||||
UINT fx_directory_first_entry_find(FX_MEDIA *media_ptr, CHAR *directory_name);
|
||||
UINT fx_directory_first_full_entry_find(FX_MEDIA *media_ptr, CHAR *directory_name,
|
||||
UINT *attributes, ULONG *size,
|
||||
UINT *year, UINT *month, UINT *day,
|
||||
UINT *hour, UINT *minute, UINT *second);
|
||||
|
||||
UINT fx_directory_information_get(FX_MEDIA *media_ptr, CHAR *directory_name,
|
||||
UINT *attributes, ULONG *size,
|
||||
UINT *year, UINT *month, UINT *day,
|
||||
UINT *hour, UINT *minute, UINT *second);
|
||||
UINT fx_directory_local_path_clear(FX_MEDIA *media_ptr);
|
||||
UINT fx_directory_local_path_get(FX_MEDIA *media_ptr, CHAR **return_path_name);
|
||||
UINT fx_directory_local_path_restore(FX_MEDIA *media_ptr, FX_LOCAL_PATH *local_path_ptr);
|
||||
UINT fx_directory_local_path_set(FX_MEDIA *media_ptr, FX_LOCAL_PATH *local_path_ptr,
|
||||
CHAR *new_path_name);
|
||||
|
||||
UINT fx_directory_long_name_get(FX_MEDIA *media_ptr, CHAR *short_name, CHAR *long_name);
|
||||
|
||||
UINT fx_directory_long_name_get_extended( FX_MEDIA *media_ptr, CHAR *short_name,
|
||||
CHAR *long_name, UINT long_file_name_buffer_length);
|
||||
|
||||
UINT fx_directory_name_test(FX_MEDIA *media_ptr, CHAR *directory_name);
|
||||
UINT fx_directory_next_entry_find(FX_MEDIA *media_ptr, CHAR *directory_name);
|
||||
UINT fx_directory_next_full_entry_find(FX_MEDIA *media_ptr, CHAR *directory_name,
|
||||
UINT *attributes, ULONG *size,
|
||||
UINT *year,UINT *month, UINT *day,
|
||||
UINT *hour, UINT *minute, UINT *second);
|
||||
|
||||
UINT fx_directory_rename(FX_MEDIA *media_ptr, CHAR *old_directory_name,
|
||||
CHAR *new_directory_name);
|
||||
|
||||
UINT fx_directory_short_name_get(FX_MEDIA *media_ptr, CHAR *long_name,
|
||||
CHAR *short_name);
|
||||
|
||||
UINT fx_directory_short_name_get_extended(FX_MEDIA *media_ptr, CHAR *long_name,
|
||||
CHAR *short_name, UINT short_file_name_length);
|
||||
```
|
||||
|
||||
## File Services
|
||||
|
||||
```c
|
||||
UINT fx_fault_tolerant_enable(FX_MEDIA *media_ptr, VOID *memory_buffer, UINT memory_size);
|
||||
UINT fx_file_allocate(FX_FILE *file_ptr, ULONG size);
|
||||
UINT fx_file_attributes_read(FX_MEDIA *media_ptr, CHAR *file_name, UINT *attributes_ptr);
|
||||
UINT fx_file_attributes_set(FX_MEDIA *media_ptr, CHAR *file_name, UINT attributes);
|
||||
UINT fx_file_best_effort_allocate(FX_FILE *file_ptr, ULONG size, ULONG *actual_size_allocated);
|
||||
UINT fx_file_close(FX_FILE *file_ptr);
|
||||
UINT fx_file_create(FX_MEDIA *media_ptr, CHAR *file_name);
|
||||
UINT fx_file_date_time_set(FX_MEDIA *media_ptr, CHAR *file_name,
|
||||
UINT year, UINT month, UINT day,
|
||||
UINT hour, UINT minute, UINT second);
|
||||
UINT fx_file_delete(FX_MEDIA *media_ptr, CHAR *file_name);
|
||||
UINT fx_file_extended_allocate(FX_FILE *file_ptr, ULONG64 size);
|
||||
UINT fx_file_extended_best_effort_allocate(FX_FILE *file_ptr, ULONG64 size,
|
||||
ULONG64 *actual_size_allocated);
|
||||
UINT fx_file_extended_relative_seek(FX_FILE *file_ptr, ULONG64 byte_offset,
|
||||
UINT seek_from);
|
||||
UINT fx_file_extended_seek(FX_FILE *file_ptr, ULONG64 byte_offset);
|
||||
UINT fx_file_extended_truncate(FX_FILE *file_ptr, ULONG64 size);
|
||||
UINT fx_file_extended_truncate_release(FX_FILE *file_ptr, ULONG64 size);
|
||||
UINT fx_file_open(FX_MEDIA *media_ptr, FX_FILE *file_ptr,
|
||||
CHAR *file_name, UINT open_type);
|
||||
UINT fx_file_read(FX_FILE *file_ptr, VOID *buffer_ptr,
|
||||
ULONG request_size, ULONG *actual_size);
|
||||
UINT fx_file_relative_seek(FX_FILE *file_ptr, ULONG byte_offset, UINT seek_from);
|
||||
UINT fx_file_rename(FX_MEDIA *media_ptr, CHAR *old_file_name,
|
||||
CHAR *new_file_name);
|
||||
UINT fx_file_seek(FX_FILE *file_ptr, ULONG byte_offset);
|
||||
UINT fx_file_truncate(FX_FILE *file_ptr, ULONG size);
|
||||
UINT fx_file_truncate_release(FX_FILE *file_ptr, ULONG size);
|
||||
UINT fx_file_write(FX_FILE *file_ptr, VOID *buffer_ptr, ULONG size);
|
||||
|
||||
UINT fx_file_write_notify_set(FX_FILE *file_ptr, VOID (*file_write_notify)(FX_FILE *file));
|
||||
```
|
||||
|
||||
## Unicode Services
|
||||
|
||||
```c
|
||||
UINT fx_unicode_directory_create(FX_MEDIA *media_ptr, UCHAR *source_unicode_name,
|
||||
ULONG source_unicode_length, CHAR *short_name);
|
||||
|
||||
UINT fx_unicode_directory_rename(FX_MEDIA *media_ptr, UCHAR *old_unicode_name,
|
||||
ULONG old_unicode_length, UCHAR *new_unicode_name,
|
||||
ULONG new_unicode_length, CHAR *new_short_name);
|
||||
|
||||
UINT fx_unicode_file_create(FX_MEDIA *media_ptr, UCHAR *source_unicode_name,
|
||||
ULONG source_unicode_length, CHAR *short_name);
|
||||
|
||||
UINT fx_unicode_file_rename(FX_MEDIA *media_ptr, UCHAR *old_unicode_name,
|
||||
ULONG old_unicode_length, UCHAR *new_unicode_name,
|
||||
ULONG new_unicode_length, CHAR *new_short_name);
|
||||
|
||||
ULONG fx_unicode_length_get(UCHAR *unicode_name);
|
||||
|
||||
|
||||
UINT fx_unicode_length_get_extended(UCHAR *unicode_name, UINT buffer_length);
|
||||
UINT fx_unicode_name_get(FX_MEDIA *media_ptr, CHAR *source_short_name,
|
||||
UCHAR *destination_unicode_name, ULONG *destination_unicode_length);
|
||||
|
||||
UINT fx_unicode_name_get_extended(FX_MEDIA *media_ptr, CHAR *source_short_name,
|
||||
UCHAR *destination_unicode_name, ULONG *destination_unicode_length,
|
||||
ULONG unicode_name_buffer_length);
|
||||
|
||||
UINT fx_unicode_short_name_get(FX_MEDIA *media_ptr, UCHAR *source_unicode_name,
|
||||
ULONG source_unicode_length, CHAR *destination_short_name);
|
||||
|
||||
UINT fx_unicode_short_name_get_extended(FX_MEDIA *media_ptr, UCHAR *source_unicode_name,
|
||||
ULONG source_unicode_length, CHAR *destination_short_name,
|
||||
ULONG short_name_buffer_length);
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Appendix D - FileX ASCII Character Codes
|
||||
description: Learn about the FileX character codes in HEX by reviewing this ASCII character code chart.
|
||||
---
|
||||
|
||||
# Appendix D - FileX ASCII character codes
|
||||
|
||||
## **ASCII Character Codes in HEX**
|
||||
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
---
|
||||
title: Chapter 1 - Introduction to FileX
|
||||
description: FileX is a complete FAT format media and file management system for deeply embedded applications.
|
||||
---
|
||||
|
||||
# Chapter 1 - Introduction to FileX
|
||||
|
||||
FileX is a complete FAT format media and file management system for deeply embedded applications. This chapter introduces FileX, describing its applications and benefits.
|
||||
|
||||
## FileX Unique Features
|
||||
|
||||
FileX supports an unlimited number of media devices at the same time, including RAM disks, FLASH managers, and actual physical devices. It supports 12-, 16-, and 32-bit File Allocation Table (FAT) formats, and also supports Extended File Allocation Table (exFAT), contiguous file allocation, and is highly optimized for both size and performance. FileX also includes fault tolerant support, media open/ close, and file write callback functions.
|
||||
|
||||
Designed to meet the growing need for FLASH devices, FileX uses the same design and coding methods as ThreadX. Like all Eclipse Foundation products, FileX is distributed with full ANSI C source code, and it has no run-time royalties.
|
||||
|
||||
### Product Highlights
|
||||
|
||||
- Complete ThreadX processor support
|
||||
- No royalties
|
||||
- Complete ANSI C source code
|
||||
- Real-time performance
|
||||
- Responsive technical support
|
||||
- Unlimited FileX objects (media, directories, and files)
|
||||
- Dynamic FileX object creation/deletion
|
||||
- Flexible memory usage
|
||||
- Size scales automatically
|
||||
- Small footprint (as low as 6 KBytes) instruction area size: 6-30K
|
||||
- Complete integration with ThreadX
|
||||
- Endian neutral
|
||||
- Easy-to-implement FileX I/O drivers
|
||||
- 12-, 16-, and 32-bit FAT support
|
||||
- exFAT support
|
||||
- Long filename support
|
||||
- Internal FAT entry cache
|
||||
- Unicode name support
|
||||
- Contiguous file allocation
|
||||
- Consecutive sector and cluster read/write
|
||||
- Internal logical sector cache
|
||||
- RAM disk demonstration runs out-of-the-box
|
||||
- Media format capability
|
||||
- Error detection and recovery
|
||||
- Fault tolerant options
|
||||
- Built-in performance statistics
|
||||
- Standalone support (No Eclipse ThreadX)
|
||||
|
||||
## Safety Certifications
|
||||
|
||||
### TÜV Certification
|
||||
|
||||
FileX has been certified by SGS-TÜV Saar for use in safety-critical systems, according to IEC-61508 SIL 4. The certification confirms that FileX can be used in the development of safety-related software for the highest safety integrity levels of IEC-61508 for the "Functional Safety of electrical, electronic, and programmable electronic safety-related systems." SGS-TUV Saar, formed through a joint venture of Germany's SGS-Group and TUV Saarland, has become the leading accredited, independent company for testing, auditing, verifying, and certifying embedded software for safety-related systems worldwide.
|
||||
|
||||
|
||||
|
||||
- IEC 61508 up to SIL 4
|
||||
|
||||
> **Important:** Please contact us for more information on which version(s) of FileX have been certified by TÜV or for the availability of test reports, certificates, and associated documentation.
|
||||
|
||||
### UL Certification
|
||||
|
||||
FileX has been certified by UL for compliance with UL 60730-1 Annex H, CSA E60730-1 Annex H, IEC 60730-1 Annex H, UL 60335-1 Annex R, IEC 603351 Annex R, and UL 1998 safety standards for software in programmable components. Along with IEC/UL 60730-1, which has requirements for "Controls Using Software" in its Annex H, the IEC 60335-1 standard describes the requirements for "Programmable Electronic Circuits" in its Annex R. IEC 60730 Annex H and IEC 60335-1 Annex R address the safety of MCU hardware and software used in appliances such as washing machines, dishwashers, dryers, refrigerators, freezers, and ovens.
|
||||
|
||||
|
||||
|
||||
_UL/IEC 60730, UL/IEC 60335, UL 1998_
|
||||
|
||||
> **Important:** Please contact us for more information on which version(s) of FileX have been certified by UL or for the availability of test reports, certificates, and associated documentation.
|
||||
|
||||
## Powerful Services of FileX
|
||||
|
||||
### Multiple Media Management
|
||||
|
||||
FileX can support an unlimited number of physical media. Each media instance has its own distinct memory area and associated driver specified on the **_fx_media_open_** call. The default distribution of FileX comes with a simple RAM media driver and a demonstration system that uses this RAM disk.
|
||||
|
||||
### Logical Sector Cache
|
||||
|
||||
By reducing the number of whole sector transfers, both to and from the media, the FileX logical sector cache significantly improves performance. FileX maintains a logical sector cache for each opened media. The depth of the logical sector cache is determined by the amount of memory supplied to FileX with the **_fx_media_open_** API call.
|
||||
|
||||
### Contiguous File Support
|
||||
|
||||
FileX offers contiguous file support through the API service **_fx_file_allocate_** to improve and make file access time deterministic. This routine takes the amount of memory requested and looks for a series of adjacent clusters to satisfy the request. If such clusters are found, they are pre-allocated by making them part of the file's chain of allocated clusters. On moving physical media, the FileX contiguous file support results in a significant performance improvement and makes the access time deterministic.
|
||||
|
||||
### Dynamic Creation
|
||||
|
||||
FileX allows you to create system resources dynamically. This is especially important if your application has
|
||||
multiple or dynamic configuration requirements. In addition, there are no predetermined limits on the number of FileX resources you can use (media or files). Also, the number of system objects does not have any
|
||||
impact on performance.
|
||||
|
||||
## Easy-to-use API
|
||||
|
||||
FileX provides the very best deeply embedded file system technology in a manner that is easy to understand and easy to use! The FileX Application Programming Interface (API) makes the services intuitive and consistent. You won't have to decipher "alphabet soup" services that are all too common with other file systems.
|
||||
|
||||
For a complete list of the FileX Version 5 Services, see [Appendix A](appendix-a.md).
|
||||
|
||||
## exFAT Support
|
||||
|
||||
exFAT (extended File Allocation Table) is a file system designed by Eclipse Foundation to allow file size to exceed 2GB, a limit imposed by FAT32 file systems. It is the default file system for SD cards with capacity over 32GB. SD cards or flash drives formatted with FileX exFAT format are compatible with Windows. exFAT supports file size up to one Exabyte (EB), which is approximately one billion GB.
|
||||
|
||||
Users wishing to use exFAT must recompile the FileX library with the symbol **_FX_ENABLE_EXFAT_** defined. When opening media, FileX detects the media type. If the media is formatted with exFAT, FileX reads and writes the file system following exFAT standard. To format new media with exFAT, use the service **_fx_media_exFAT_format_**. By default exFAT is not enabled.
|
||||
|
||||
## Fault Tolerant Support
|
||||
|
||||
The FileX Fault Tolerant Module is designed to prevent file system corruption caused by interruptions during the file or directory update. For example, when appending data to a file, FileX needs to update the content of the file, the directory entry, and possibly the FAT entries. If this sequence of update is interrupted (such as power glitch, or the media is ejected in the middle of the update), the file system is in an inconsistent state, which may affect the integrity of the entire file system, leading towards corruption of other files.
|
||||
|
||||
The FileX Fault Tolerant Module works by recording all steps required to update a file or a directory along the way. This log entry is stored on the media in dedicated sectors (blocks) that FileX can find and access. The location of the log data can be accessed even without a proper file system. Therefore, in case the file system is corrupted, FileX is still able to find the log entry and restore the file system back into a good state.
|
||||
|
||||
As FileX updates file or directory, log entries are created. After the update operation is successfully completed, the log entries are removed. If the log entries were not properly removed after a successful file update, if the recovery process determines that the content in the log entry matches the file system, nothing needs to be done, and the log entries can be cleaned up.
|
||||
|
||||
In case the file system update operation was interrupted, next time the media is mounted by FileX, the Fault Tolerant Module analyzes the log entries. The information in the log entries allows FileX to back out partial changes already applied to the file system (in case the failure happens during the early stage of the file update operation), or if the log entries contain re-do information, FileX is able to apply the changes required to finish the prior operation.
|
||||
|
||||
This fault tolerant feature is available to all FAT file systems supported by FileX, including FAT12, FAT16, FAT32, and exFAT. By default fault tolerant is not enabled in FileX. To enable the fault tolerant feature, FileX must be built with the symbol **FX_ENABLE_FAULT_TOLERANT** and **FX_FAULT_TOLERANT** defined. At run time, the application starts fault tolerant service by calling **_fx_fault_tolerant_enable_**.
|
||||
After the service starts, all file and directory write operations go through the Fault Tolerant Module.
|
||||
|
||||
As fault tolerant service starts, it first detects whether or not the media is protected under the Fault Tolerant Module. If it is not, FileX assumes integrity of the file system, and starts protection by allocating free blocks from the file system to be used for logging and caching. If the Fault Tolerant Module logs are found on the file system, it analyzes the log entries. FileX reverts the prior operation or redoes the prior operation, depending on the content of the log entries. The file system becomes available after all the prior log entries are processed. This ensures that FIleX starts from a known good state.
|
||||
|
||||
After a media is protected under the FileX Fault Tolerant Module, the media will not be updated with another file system. Doing so would leave the log entries on the file system inconsistent with the contents in the FAT table, the directory entry. If the media is updated by another file system before moving it back to FileX with the Fault Tolerant Module, the result is undefined.
|
||||
|
||||
## Callback Functions
|
||||
|
||||
The following three callback functions are added to FileX:
|
||||
|
||||
- Media Open callback
|
||||
- Media Close callback
|
||||
- File Write callback
|
||||
|
||||
After registered, these functions will notify the application when such events occur.
|
||||
|
||||
## Easy Integration
|
||||
|
||||
FileX is easily integrated with virtually any FLASH or media device. Porting FileX is simple. This guide describes the process in detail, and the RAM driver of the demo system makes for a very good place to start!
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
title: Chapter 2 - Installation and use of FileX
|
||||
description: This chapter contains an introduction to FileX and a description of installation conditions, procedures, and use, including the following.
|
||||
---
|
||||
|
||||
# Chapter 2 - Installation and use of FileX
|
||||
|
||||
This chapter contains an introduction to FileX and a description of installation conditions, procedures, and use.
|
||||
|
||||
## Host Considerations
|
||||
|
||||
### Computer Type
|
||||
|
||||
Embedded development is usually performed on Windows or Linux (Unix) host computers. After the application is compiled, linked, and located on the host, it is downloaded to the target hardware for execution.
|
||||
|
||||
### Download Interfaces
|
||||
|
||||
Usually the target download is done from within the development tool's debugger. After download, the debugger is responsible for providing target execution control (go, halt, breakpoint, etc.) as well as access to memory and processor registers.
|
||||
|
||||
### Debugging Tools
|
||||
|
||||
Most development tool debuggers communicate with the target hardware via on-chip debug (OCD) connections such as JTAG (IEEE 1149.1) and Background Debug Mode (BDM). Debuggers also communicate with target hardware through In-Circuit Emulation (ICE) connections. Both OCD and ICE connections provide robust solutions with minimal intrusion on the target resident software.
|
||||
|
||||
### Required Hard Disk Space
|
||||
|
||||
The source code for FileX is delivered in ASCII format and requires approximately 500 KBytes of space on the host computer's hard disk
|
||||
|
||||
## Target Considerations
|
||||
|
||||
FileX requires between 6 KBytes and 30 KBytes of Read-Only Memory (ROM) on the target. Another 100 bytes of the target's Random Access Memory (RAM) are required for FileX global data structures. Each opened media also requires 1.5 KBytes of RAM for the control block in addition to RAM for storing data for one sector (typically 512 bytes).
|
||||
|
||||
For date/time stamping to function properly, FileX relies on ThreadX timer facilities. This is implemented by creating a FileX-specific timer during FileX initialization. FileX also relies on ThreadX semaphores for multiple thread protection and I/O suspension.
|
||||
|
||||
## Product Distribution
|
||||
|
||||
FileX can be obtained from our public source code repository at <https://github.com/azure-rtos/filex/>.
|
||||
|
||||
The following is a list of several important files in the repository:
|
||||
|
||||
- ***fx_api.h*** : This C header file contains all system equates, data structures, and service prototypes.
|
||||
- ***fx_port.h*** : This C header file contains all development-tool-specific data definitions and structures.
|
||||
- ***demo_filex.c*** : This C file contains a small demo application.
|
||||
- ***fx.a (or fx.lib)*** : This is the binary version of the FileX C library. It is distributed with the standard package.
|
||||
|
||||
> **Important:** *All file names are in lower-case. This naming convention makes it easier to convert the commands to Linux (Unix) development platforms.*
|
||||
|
||||
## FileX Installation
|
||||
|
||||
FileX is installed by cloning the GitHub repository to your local machine. The following is typical syntax for creating a clone of the FileX repository on your PC:
|
||||
|
||||
```c
|
||||
git clone https://github.com/azure-rtos/filex
|
||||
```
|
||||
|
||||
Alternatively you can download a copy of the repository using the download button on the GitHub main page.
|
||||
|
||||
You will also find instructions for building the FileX library on the front page of the online repository.
|
||||
|
||||
> **Important:** Application software needs access to the FileX library file (usually called* usually ***fx.a*** or ***fx.lib***) *and the C include files **fx_api.h** and **fx_port.h**. This is accomplished either by setting the appropriate path for the development tools or by copying these files into the application development area.
|
||||
|
||||
## Using FileX
|
||||
|
||||
Using FileX is easy. Basically, the application code must include ***fx_api.h*** during compilation and link with the FileX run-time library ***fx.a*** (or ***fx.lib***). Of course, the ThreadX files, namely ***tx_api.h*** and ***tx.a*** (or ***tx.lib***)*,* are also required.
|
||||
|
||||
> **Important:** When using FileX in Standalone mode (**FX_STANDALONE_ENABLE** must be defined), ThreadX files/libraries are not required.
|
||||
|
||||
Assuming you are already using ThreadX, there are four steps required to build a FileX application:
|
||||
|
||||
1. Include the ***fx_api.h*** file in all application files that use FileX services or data structures.
|
||||
1. Initialize the FileX system by calling ***fx_system_initialize*** from the ***tx_application_define*** function or an application thread.
|
||||
|
||||
> **Important:** When using FileX in Standalone mode, ***fx_system_initialize*** should be directly called from application code.
|
||||
|
||||
1. Add one or more calls to ***fx_media_open*** to set up the FileX media. This call must be made from the context of an application thread.
|
||||
|
||||
> **Important:** *Remember that the **fx_media_open** call requires enough RAM to store data for one sector.*
|
||||
|
||||
1. Compile application source and link with the FileX and ThreadX run-time libraries, ***fx.a*** (or ***fx.lib***) and ***tx.a*** (or ***tx.lib***). The resulting image can be downloaded to the target and executed!
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Each FileX port is delivered with a demonstration application. It is always a good idea to get the demonstration system running first—either on the target hardware or a specific demonstration environment.
|
||||
|
||||
If the demonstration system does not work, try the following things to narrow the problem:
|
||||
|
||||
1. Determine how much of the demonstration is running.
|
||||
1. Increase stack sizes (this is more important in actual application code than it is for the demonstration).
|
||||
1. Ensure there is enough RAM for the 32KBytes default RAM disk size. The basic system will operate on much less RAM; however, as more of the RAM disk is used, problems will surface if there is not enough memory.
|
||||
1. Temporarily bypass any recent changes to see if the problem disappears or changes.
|
||||
|
||||
## Configuration Options
|
||||
|
||||
There are several configuration options when building the FileX library and the application using FileX. The options below can be defined in the application source, on the command line, or within the ***fx_user.h*** include file.
|
||||
|
||||
> **Important:** *Options defined in **fx_user.h** are applied only if the application and ThreadX library are built with ***FX_INCLUDE_USER_DEFINE_FILE*** defined.*
|
||||
> When using FileX in Standalone mode (**FX_STANDALONE_ENABLE** must be defined), ThreadX files/libraries are not required.
|
||||
|
||||
The following list describes each configuration option in detail:
|
||||
|
||||
|Define|Meaning|
|
||||
|---------- |-----------|
|
||||
|FX_MAX_LAST_NAME_LEN |This value defines the maximum file name length, which includes full path name. By default, this value is 256.|
|
||||
|FX_DONT_UPDATE_OPEN_FILES |Defined, FileX does not update already opened files.|
|
||||
|FX_MEDIA_DISABLE_SEARCH_CACHE |Defined, the file search cache optimization is disabled.|
|
||||
|FX_MEDIA_DISABLE_SEARCH_CACHE |Defined, the file search cache optimization is disabled.|
|
||||
|FX_DISABLE_DIRECT_DATA_READ_CACHE_FILL |Defined, the direct read sector update of cache is disabled.|
|
||||
|FX_MEDIA_STATISTICS_DISABLE |Defined, gathering of media statistics is disabled.|
|
||||
|FX_SINGLE_OPEN_LEGACY |Defined, legacy single open logic for the same file is enabled.|
|
||||
|FX_RENAME_PATH_INHERIT |Defined, renaming inherits path information.|
|
||||
|FX_DISABLE_ERROR_CHECKING |Removes the basic FileX error checking API and results in improved performance (as much as 30%) and smaller code size.|
|
||||
|FX_MAX_LONG_NAME_LEN |Specifies the maximum file name size for FileX. The default value is 256, but this can be overridden with a command-line define. Legal values range between 13 and 256.|
|
||||
|FX_MAX_SECTOR_CACHE|Specifies the maximum number of logical sectors that can be cached by FileX. The actual number of sectors that can be cached is lesser of this constant and how many sectors can fit in the amount of memory supplied at fx_media_open. The default value is 256. All values must be a power of 2.|
|
||||
|FX_FAT_MAP_SIZE |Specifies the number of sectors that can be represented in the FAT update map. The default value is 256, but this can be overridden with a command-line define. Larger values help reduce unneeded updates of secondary FAT sectors.|
|
||||
|FX_MAX_FAT_CACHE |Specifies the number of entries in the internal FAT cache. The default value is 16, but this can be overridden with a command-line define. All values must be a power of 2.|
|
||||
|FX_FAULT_TOLERANT |When defined, FileX immediately passes write requests of all system sectors (boot, FAT, and directory sectors) to the media's driver. This potentially decreases performance, but helps limit corruption to lost clusters. Note that enabling this feature does not automatically enable FileX Fault Tolerant Module, which is enabled by defining|
|
||||
|FX_FAULT_TOLERANT_DATA |When defined, FileX immediately passes all file data write requests to the media's driver. This potentially decreases performance, but helps limit lost file data. Note that enabling this feature does not automatically enable FileX Fault Tolerant Module, which is enabled by defining ***FX_ENABLE_FAULT_TOLERANT***|
|
||||
|FX_NO_LOCAL_PATH|Removes local path logic from FileX, resulting in smaller code size.|
|
||||
|FX_NO_TIMER|Eliminates the ThreadX timer setup to update the FileX system time and date. Doing so causes default time and date to be placed on all file operations.|
|
||||
|FX_UPDATE_RATE_IN_SECONDS |Specifies rate at which system time in FileX is adjusted. By default, value is 10, specifying that the FileX system time is updated every 10 seconds.|
|
||||
|FX_ENABLE_EXFAT| When defined, the logic for handling exFAT file system is enabled in FileX. By default this symbol is not defined.|
|
||||
|FX_UPDATE_RATE_IN_TICKS| Specifies the same rate as ***FX_UPDATE_RATE_IN_SECONDS*** (see above), except in terms of the underlying ThreadX timer frequency. The default is 1000, which assumes a 10ms ThreadX timer rate and a 10 second interval.|
|
||||
|FX_SINGLE_THREAD|Eliminates ThreadX protection logic from the FileX source. It should be used if FileX is being used only from one thread or if FileX is being used without ThreadX.|
|
||||
|FX_DRIVER_USE_64BIT_LBA|When defined, enables 64-bit sector addresses used in I/O driver. By default this option is not defined.|
|
||||
|FX_ENABLE_FAULT_TOLERANT| When defined, enables FileX Fault Tolerant Module. Enabling Fault Tolerant automatically defines the symbol ***FX_FAULT_TOLERANT*** and ***FX_FAULT_TOLERANT_DATA***. By default this option is not defined.|
|
||||
|FX_FAULT_TOLERANT_BOOT_INDEX|Defines byte offset in the boot sector where the cluster for the fault tolerant log is. By default this value is 116. This field takes 4 bytes. Bytes 116 through 119 are chosen because they are marked as reserved by FAT 12/16/32/exFAT specification.|
|
||||
|FX_FAULT_TOLERANT_MINIMAL_CLUSTER|This symbol is deprecated. It is no longer being used by FileX Fault Tolerant.|
|
||||
|FX_STANDALONE_ENABLE|Defined, enables FileX to be used in standalone mode (without Eclipse ThreadX). By default this symbol is not defined.|
|
||||
|
||||
> **Important:** When **FX_STANDALONE_ENABLE** is defined, Local path logic and ThreadX timer setup are disabled.
|
||||
|
||||
## FileX Version ID
|
||||
|
||||
The current version of FileX is available both to the user and the application software during run-time. The programmer can obtain the FileX version from examination of the **fx_port.h** file. In addition, this file also contains a version history of the corresponding port. Application software can obtain the FileX version by examining the global string ***_fx_version_id***.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: Chapter 6 - FileX fault tolerant module
|
||||
description: This chapter contains a description of the FileX Fault Tolerant Module that is designed to maintain file system integrity if the media loses power or is ejected in the middle of a file write operation.
|
||||
---
|
||||
|
||||
# Chapter 6 - FileX fault tolerant module
|
||||
|
||||
This chapter contains a description of the FileX Fault Tolerant Module that is designed to maintain file system integrity if the media loses power or is ejected in the middle of a file write operation.
|
||||
|
||||
## FileX Fault Tolerant Module Overview
|
||||
|
||||
When an application writes data into a file, FileX updates both data clusters and system information. These updates must be completed as an atomic operation to keep information in the file system coherent. For example, when appending data to a file, FileX needs to find an available cluster in the media, update the FAT chain, update the length filed in the directory entry, and possibly update the starting cluster number in the directory entry. Either a power failure or media ejection can interrupt the sequence of updates, which will leave the file system in an inconsistent state. If the inconsistent state is not corrected, the data being updated can be lost, and because of damage to the system information, subsequent file system operation may damage other files or directories on the media.
|
||||
|
||||
The FileX Fault Tolerant Module works by journaling steps required to update a file *before* these steps are applied to the file system. If the file update is successful, these log entries are removed. However, if the file update is interrupted, the log entries are stored on the media. Next time the media is mounted, FileX detects these log entries from the previous (unfinished) write operation. In such cases, FileX can recover from a failure by either rolling back the changes already made to the file system, or by reapplying the required changes to complete the previous operation. In this way, the FileX Fault Tolerant Module maintains file system integrity if the media loses power during an update operation.
|
||||
|
||||
> **Important:** *The FileX Fault Tolerant Module is not designed to prevent file system corruption caused by physical media corruption with valid data in it.*
|
||||
|
||||
> **Important:** *After the FileX Fault Tolerant module protects a media, the media must not be mounted by anything other than FileX with Fault Tolerant enabled. Doing so can cause the log entries in the file system to be inconsistent with system information on the media. If the FileX Fault Tolerant module attempts to process log entries after the media is updated by another file system, the recovery procedure may fail, leaving the entire file system in an unpredictable state.*
|
||||
|
||||
## Use of the Fault Tolerant Module
|
||||
|
||||
The FileX Fault Tolerant feature is available to all FAT file systems supported by FileX, including FAT12, FAT16, FAT32, and exFAT. To enable the fault tolerant feature, FileX must be built with the symbol **FX_ENABLE_FAULT_TOLERANT** defined. At run time, application starts fault tolerant service by calling ***fx_fault_tolerant_enable*** immediately after the call to ***fx_media_open***. After fault tolerant is enabled, all file write operations to the designated media are protected. By default the fault tolerant module is not enabled.
|
||||
|
||||
> **Important:** *Application needs to make sure the file system is not being accessed prior to ***fx_fault_tolerant_enable*** being called. If application writes data to the file system prior to fault tolerant enable, the write operation could corrupt the media if prior write operations were not completed, and the file system was not restored using fault tolerant log entries.*
|
||||
|
||||
## FileX Fault Tolerant Module Log
|
||||
|
||||
The FileX fault tolerant log takes up one logical cluster in flash. The index to the starting cluster number of that cluster is recorded in the boot sector of the media, with an offset specified by the symbol **FX_FAULT_TOLERANT_BOOT_INDEX**. By default this symbol is defined to be 116. This location is chosen because it is marked as reserved in FAT12/ 16/32 and exFAT specification.
|
||||
|
||||
Figure 5, "Log Structure Layout," shows the general layout of the log structure. The log structure contains three sections: Log Header, FAT Chain, and Log Entries.
|
||||
|
||||
> **Important:** *All multi-byte values stored in the log entries are in Little Endian format.*
|
||||
|
||||
|
||||
|
||||
**Figure 5. Log Structure Layout**
|
||||
|
||||
The Log Header area contains information that describes the entire log structure and explains each field in detail.
|
||||
|
||||
**TABLE 8. Log Header Area**
|
||||
|
||||
|Field|Size(in bytes)|Description|
|
||||
|-----|--------------|-----------|
|
||||
|ID|4|Identifies a FileX Fault Tolerant Log structure. The log structure is considered invalid if the ID value is not 0x46544C52.|
|
||||
|Total Size|2|Indicates the total size (in bytes) of the entire log structure.|
|
||||
|Header Checksum|2|Checksum that converts the log header area. The log structure is considered invalid if the header fields fail the checksum verification.|
|
||||
|Version Number|2|FileX Fault Tolerant major and minor version numbers.|
|
||||
|Reserved|2|For future expansion.|
|
||||
|
||||
The Log Header area is followed by the FAT Chain Log area. Figure 9 contains information that describes how the FAT chain should be modified. This log area contains information on the clusters being allocated to a file, the clusters being removed from a file, and where the insertion/deletion should be and describes each field in the FAT Chain Log area.
|
||||
|
||||
**TABLE 9. FAT Chain Log Area**
|
||||
|
||||
|Field|Size(in bytes)|Description|
|
||||
|-----|--------------|-----------|
|
||||
|FAT Chain Log Checksum|2|Checksum of the entire FAT Chain Log area. The FAT Chain Log area is considered invalid if the it fails the checksum verification.|
|
||||
|Flag|1|Valid flag values are:<br/>0x01 FAT Chain Valid<br />0x02 BITMAP is being used|
|
||||
|Reserved|1|Reserved for future use|
|
||||
|Insertion Point – Front|4|The cluster (that belongs to the original FAT chain) where the newly created chain is going to be attached to.|
|
||||
|Head Cluster of New FAT Chain|4|The first cluster of the newly created FAT Chain|
|
||||
|Head Cluster of Original FAT Chain|4|The first cluster of the portion of the original FAT Chain that is to be removed.|
|
||||
|Insertion Point – Back|4|The original cluster where the newly created FAT chain joins at.|
|
||||
|Next Deletion Point|4|This field assists the FAT chain cleanup procedure.|
|
||||
|
||||
The Log Entries Area contains log entries that describe the changes needed to recover from a failure. There are three types of log entry supported in the FileX fault tolerant module: FAT Log Entry; Directory Log Entry; and Bitmap Log Entry.
|
||||
|
||||
The following three figures and three tables describe these log entries in detail.
|
||||
|
||||
|
||||
|
||||
**Figure 6. FAT Log Entry**
|
||||
|
||||
**TABLE 10. FAT Log Entry**
|
||||
|
||||
|Field|Size(in bytes)|Description|
|
||||
|-----|--------------|-----------|
|
||||
Type|2|Type of Entry, must be FX_FAULT_TOLERANT_FAT_LOG_TYPE|
|
||||
|Size|2|Size of this entry|
|
||||
|Cluster Number|4|Cluster number|
|
||||
|Value|4|Value to be written into the FAT entry|
|
||||
|
||||
|
||||
|
||||
**Figure 7. Directory Log Entry**
|
||||
|
||||
**TABLE 11. Directory Log Entry**
|
||||
|
||||
|Field|Size(in bytes)|Description|
|
||||
|-----|--------------|-----------|
|
||||
|Type|2|Type of Entry, must be FX_FAULT_TOLERANT_DIRECTORY_LOG_TYPE|
|
||||
|Size|2|Size of this entry|
|
||||
|Sector Offset|4|Offset (in bytes) into the sector where this directory is located.|
|
||||
|Log Sector|4|The sector where the directory entry is located|
|
||||
|Log Data|Variable|Content of the directory entry|
|
||||
|
||||
|
||||
|
||||
**Figure 8. Bitmap Log Entry**
|
||||
|
||||
**TABLE 12. Bitmap Log Entry**
|
||||
|
||||
|Field|Size(in bytes)|Description|
|
||||
|-----|--------------|-----------|
|
||||
|Type|2|Type of Entry, must be FX_FAULT_TOLERANT_BITMAP_LOG_TYPE|
|
||||
|Size|2|Size of this entry|
|
||||
|Cluster Number|4|Cluster number|
|
||||
|Value|4|Value to be written into the FAT entry|
|
||||
|
||||
## Fault Tolerant Protection
|
||||
|
||||
After the FileX Fault Tolerant Module starts, it first searches for an existing fault tolerant log file in the media. If a valid log file cannot be found, FileX considers the media unprotected. In this case FileX will create a fault tolerant log file on the media.
|
||||
|
||||
> **Important:** *FileX is not able to protect a file system if it was corrupted before the FileX Fault Tolerant Module starts.*
|
||||
|
||||
If a fault tolerant log file is located, FileX checks for existing log entries. A log file with no log entry indicates prior file operation was successful, and all log entries were removed. In this case the application can start using the file system with fault tolerant protection.
|
||||
|
||||
However if log entries are located, FileX needs to either complete the prior file operation, or revert the changes already applied to the file system, effectively undo the changes. In either case, after the log entries are applied to the file system, the file system is restored into a coherent state, and application can start using the file system again.
|
||||
|
||||
For media protected by FileX, during file update operation, the data portion is written directly to the media. As FileX writes data, it also records any changes needed to be applied to directory entries, FAT table. This information is recorded in the file tolerant log entries. This approach guarantees that updates to the file system occur after the data is written to the media. If the media is ejected during the data-write phase, crucial file system information has not been changed yet. Therefore the file system is not affected by the interruption.
|
||||
|
||||
After all the data is successfully written to the media, FileX then follows information in the log entries to applies the changes to system information, one entry at a time. After all the system information is committed to the media, the log entries are removed from the fault tolerant log. At this point, FileX completes the file update operation.
|
||||
|
||||
During file update operation, files are not updated in place. The fault tolerant module allocates a sector for the data to write the new data into, and then remove the sector that contains the data to be overwritten, updating related FAT entries to link the new sector into the chian. For situations in which partial data in a cluster needs to be modified, FileX always allocates new clusters, writes the entire data from the old clusters with updated data into the new clusters, then frees up the old clusters. This guarantees that if the file update is interrupted, the original file is intact. The application needs to be aware that under FileX fault tolerant protection, updating data in a file requires the media to have enough free space to hold new data before sectors with old data can be released. If the media doesn't have enough space to hold new data, the update operation fails.
|
||||
@@ -0,0 +1,28 @@
|
||||
# FileX documentation
|
||||
|
||||
[Overview of FileX](overview-filex.md)
|
||||
|
||||
FileX user guide
|
||||
- [About this guide](about-this-guide.md)
|
||||
- [Ch. 1 - Introduction to FileX](chapter1.md)
|
||||
- [Ch. 2 - Installation and use of FileX](chapter2.md)
|
||||
- [Ch. 3 - Functional components of FileX](chapter3.md)
|
||||
- [Ch. 4 - Description of FileX services](chapter4.md)
|
||||
- [Ch. 5 - I/O drivers for FileX](chapter5.md)
|
||||
- [Ch. 6 - FileX fault tolerant module](chapter6.md)
|
||||
- [App. A - FileX services](appendix-a.md)
|
||||
- [App. B - FileX constants](appendix-b.md)
|
||||
- [App. C - FileX data types](appendix-c.md)
|
||||
- [App. D - ASCII character codes](appendix-d.md)
|
||||
|
||||
[FileX repository](https://github.com/azure-rtos/filex)
|
||||
|
||||
[Eclipse ThreadX components](../../README.md)
|
||||
- [ThreadX](../threadx/index.md)
|
||||
- [ThreadX Modules](../threadx-modules/index.md)
|
||||
- [NetX Duo](../netx-duo/index.md)
|
||||
- [GUIX](../guix/index.md)
|
||||
- [FileX](../filex/index.md)
|
||||
- [LevelX](../levelx/index.md)
|
||||
- [USBX](../usbx/index.md)
|
||||
- [TraceX](../tracex/index.md)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 110 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 79 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.8 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.3 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.8 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.5 KiB |
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Understand FileX
|
||||
description: FileX is a high-performance, file allocation table (FAT)-compatible file system that's fully integrated with ThreadX and available for all supported processors. Like ThreadX, FileX is designed to have a small footprint and high performance, making it ideal for today's deeply embedded applications that require file management operations. FileX supports most physical media, including RAM, USBX, SD CARD, and NAND/NOR flash memories via LevelX.
|
||||
---
|
||||
|
||||
# Overview of FileX
|
||||
|
||||
FileX embedded file system is Eclipse ThreadX's advanced, industrial grade solution for Eclipse Foundation FAT file formats, designed specifically for deeply embedded, real-time, and IoT applications. FileX supports all of Eclipse Foundation's file formats, including FAT12, FAT16, FAT32, and exFAT. FileX also offers optional fault tolerance and FLASH wear leveling via an add-on product called [LevelX](../levelx/index.md). All of this combined with a small footprint, fast execution, and superior ease-of-use, make FileX the ideal choice for the most demanding embedded IoT applications.
|
||||
|
||||
## API protocols
|
||||
|
||||
### Media Services
|
||||
|
||||
- FAT 12/16/32 and exFAT support
|
||||
- Minimal 6KB FLASH, 2.5KB RAM
|
||||
- Complete media access services
|
||||
- Unlimited number of media instance
|
||||
- Simple read/write logical sector driver interface
|
||||
- Multiple partition support
|
||||
- Logical sector cache
|
||||
- FAT entry cache
|
||||
- Optional fault tolerance support
|
||||
- Deferred Secondary FAT update
|
||||
- System-level Trace via TraceX
|
||||
- Intuitive media access APIs, including:
|
||||
- fx_media_open
|
||||
- fx_media_close
|
||||
- fx_media_format
|
||||
- fx_media_space_available
|
||||
|
||||
### Directory Services
|
||||
|
||||
- Up to 256 byte paths
|
||||
- Long and 8.3 directory names supported
|
||||
- Directory create & delete
|
||||
- Directory navigation and traversal
|
||||
- Directory attributes management
|
||||
- System-level Trace via TraceX
|
||||
- Intuitive directory access APIs, including:
|
||||
- fx_directory_create
|
||||
- fx_directory_delete
|
||||
- fx_directory_attributes_set
|
||||
- fx_directory_attributes_read
|
||||
- fx_directory_first_entry_find
|
||||
- fx_directory_next_entry_find
|
||||
|
||||
### File Services
|
||||
|
||||
- Minimal 3.3KB FLASH
|
||||
- Unlimited open files
|
||||
- Read-only files can be opened multiple times
|
||||
- Long and 8.3 directory names supported
|
||||
- Contiguous file support
|
||||
- Fast seek logic
|
||||
- Pre-allocation of clusters
|
||||
- File create, delete, and rename
|
||||
- File read, write, and see
|
||||
- File attributes management
|
||||
- System-level Trace via TraceX
|
||||
- Intuitive file access APIs, including:
|
||||
- fx_file_create
|
||||
- fx_file_delete
|
||||
- fx_file_attributes_set
|
||||
- fx_file_attributes_read
|
||||
- fx_file_read
|
||||
- fx_file_seek
|
||||
- fx_file_write
|
||||
|
||||
## Advanced technology
|
||||
|
||||
FileX is advanced technology, including the following.
|
||||
|
||||
- FAT 12/16/32 and exFAT support
|
||||
- Multiple partition support
|
||||
- Automatic scaling
|
||||
- Endian neutral
|
||||
- Long file name and 8.3 support
|
||||
- Optional fault tolerance support
|
||||
- Logical sector cache
|
||||
- FAT entry cache
|
||||
- Pre-allocation of clusters
|
||||
- Contiguous file support
|
||||
- Optional performance metrics
|
||||
- TraceX system analysis support
|
||||
|
||||
## NOR/NAND Wear Leveling (LevelX)
|
||||
|
||||
LevelX is Eclipse Foundation's NOR/NAND FLASH wear leveling product. LevelX can be used in conjunction with FileX or as a stand-alone, direct read/write FLASH sector library for the application.
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Product Support Policy
|
||||
description: Eclipse ThreadX Product Support Policy.
|
||||
---
|
||||
# Product Support Policy
|
||||
|
||||
This document applies for Eclipse ThreadX components including ThreadX, NetX Duo, FileX, GUIX, USBX and LevelX.
|
||||
|
||||
## Version definitions
|
||||
|
||||
Eclipse ThreadX releases generally follow the guidelines defined by [Semantic Versioning](https://semver.org/). Given an Eclipse ThreadX version number **X.Y.Z** (e.g. 6.1.9):
|
||||
|
||||
* **X** increases for a **milestone release**. Currently Eclipse ThreadX components stay at version **6**.
|
||||
* **Y** increases for a **feature release** when there is a major feature added (e.g. v6.**1**.0 introduced Eclipse ThreadX IoT Middleware).
|
||||
* **Z** increases for a every three month **regular updates** or **patch** for critical bug fixes.
|
||||
|
||||
## Roadmap
|
||||
|
||||
Last updated: **2021/11**
|
||||
|
||||
|
||||
|
||||
## Support policy
|
||||
|
||||
Eclipse ThreadX provides 60 months support for each milestone release (e.g. v6.x.x) and 24 months for each feature release (e.g. v6.1.x). The **Maintenance** or so called **LTS (Long-term-support)** period starts right after a new feature release is published. Eclipse ThreadX version 6.0.0 and all future releases will follow this support policy.
|
||||
|
||||
The entire life cycle of a certain feature release (e.g. v6.1.x) can be broken down into **Service** and **Maintenance** periods:
|
||||
|
||||
| **Period** | **Duration** | **Definition** |
|
||||
| --- | --- | --- |
|
||||
| Service | Subject to the actual development plan | New features and regular bug fixes |
|
||||
| Maintenance (LTS) | 24 months after next feature release published | Critical and security bug fixes |
|
||||
|
||||
### Example
|
||||
|
||||
* Eclipse ThreadX v6.1.0 was released in 2020/10, it will be actively in development with bug fixes for the regular update version (e.g. v6.1.11 released in 2022/04).
|
||||
* Users are always welcomed to update to the latest version during the Service period.
|
||||
* When Eclipse ThreadX v6.2.0 is released. The latest v6.1.x will get into the Maintenance (LTS) period. We will keep backporting important bug fixes from v6.2.x to it. Until 24 months later, which v6.1.x will come to End Of Life.
|
||||
|
||||
The actual duration of each feature release may varies depending on the actual development plan. Please view the [Roadmap](#roadmap) section above for the recent feature release versions.
|
||||
|
||||
### Other notes
|
||||
|
||||
* Users are recommended starting a new project using release in Service period.
|
||||
* Users are encouraged to upgrade all projects to a newer Eclipse ThreadX release before the support period finishes.
|
||||
* For particular cases users cannot upgrade the projects, security / critical bug fixes can be applied to it with communication with Eclipse Foundation.
|
||||
* Pre-release version (public preview, pre-release and etc.,) or feature marked as "Preview" are not covered by any support period.
|
||||
* For prior releases to v6. The support is covered by ExpressLogic support contract.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Security Updates
|
||||
description: Eclipse ThreadX Security Updates.
|
||||
---
|
||||
# Security Updates
|
||||
|
||||
This table lists all [Common Vulnerabilities and Exposures (CVE)](https://cve.mitre.org/) and status for fixes in Eclipse ThreadX components.
|
||||
|
||||
For all security vulnerabilities, you can find the published list on the corresponding Eclipse ThreadX component repository.
|
||||
|
||||
| Release Date | CVE | Severity | Eclipse ThreadX Component | Affected Versions | Patched Versions
|
||||
| - | - | - | - | - | - |
|
||||
| 5/19/2022 | [CVE-2022-29246](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29246) | High | USBX | < 6.1.11 | 6.1.11 |
|
||||
| 5/17/2022 | [CVE-2022-29223](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2022-29223) | High | USBX | < 6.1.10 | 6.1.10 |
|
||||
| 11/9/2021 | [CVE-2021-42323](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42323) | High | USBX | < 6.1.9 | 6.1.9 |
|
||||
| 11/9/2021 | [CVE-2021-42304](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42304) | High | USBX | < 6.1.9 | 6.1.9 |
|
||||
| 11/9/2021 | [CVE-2021-42303](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42303) | High | USBX | < 6.1.9 | 6.1.9 |
|
||||
| 11/9/2021 | [CVE-2021-42302](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42302) | High | USBX | < 6.1.9 | 6.1.9 |
|
||||
| 11/9/2021 | [CVE-2021-42301](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-42301) | High | USBX | < 6.1.9 | 6.1.9 |
|
||||
| 11/9/2021 | [CVE-2021-26444](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-26444) | High | USBX | < 6.1.9 | 6.1.9 |
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: GUIX Studio User Guide
|
||||
description: This guide provides comprehensive information about GUIX Studio, the Microsoft Windows-based rapid UI development environment specifically designed for the GUIX runtime library from Eclipse Foundation.
|
||||
---
|
||||
# About This GUIX Studio User Guide
|
||||
|
||||
This guide provides comprehensive information about GUIX Studio, the Microsoft Windows-based rapid UI development environment specifically designed for the GUIX runtime library from Eclipse Foundation.
|
||||
|
||||
It is intended for the embedded real-time software developer using the ThreadX Real-Time Operating System (RTOS) and the GUIX UI run-time library. The developer should be familiar with standard ThreadX and GUIX concepts.
|
||||
|
||||
## Organization
|
||||
|
||||
- [**Chapter 1**](guix-studio-1.md) provides a basic overview of GUIX Studio and its relationship to real-time development.
|
||||
- [**Chapter 2**](guix-studio-2.md) gives the basic steps to install and use GUIX Studio to analyze your application right out of the box.
|
||||
- [**Chapter 3**](guix-studio-3.md) describes the main features of GUIX Studio.
|
||||
- [**Chapter 4**](guix-studio-4.md) describes how to use GUIX Studio to create and manage your application resources.
|
||||
- [**Chapter 5**](guix-studio-5.md) describes how to use the GUIX WYSIWYG screen designer.
|
||||
- [**Chapter 6**](guix-studio-6.md) describes how your application will utilize the output files and API functions generated by GUIX Studio.
|
||||
- [**Chapter 7**](guix-studio-7.md) describes how to configure screen flow
|
||||
- [**Chapter 8**](guix-studio-8.md) describes the usage of command line tool
|
||||
- [**Chapter 9**](guix-studio-9.md) describes a simple but complete UI application created by GUIX Studio.
|
||||
- [**Chapter 10**](guix-studio-10.md) describes how to create an example project in GUIX Studio and execute the example on GUIX.
|
||||
- [**Chapter 11**](guix-studio-11.md) describes the resource project file and its usage.
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: GUIX User Guide
|
||||
description: This guide contains comprehensive information about GUIX, the high-performance GUI product from Eclipse Foundation.
|
||||
---
|
||||
# About GUIX User Guide
|
||||
|
||||
This guide contains comprehensive information about GUIX, the high-performance GUI product from Eclipse Foundation. It is intended for embedded real-time software developers familiar with basic GUI concepts, ThreadX, and the C programming language.
|
||||
|
||||
## Organization
|
||||
|
||||
[Chapter 1 - Introduction to GUIX](chapter-1.md)
|
||||
|
||||
[Chapter 2 - Installation and use of GUIX](chapter-2.md)
|
||||
|
||||
[Chapter 3 - Functional Overview of GUIX](chapter-3.md)
|
||||
|
||||
[Chapter 4 - Description of GUIX Services](chapter-4.md)
|
||||
|
||||
[Chapter 5 - GUIX Display Drivers](chapter-5.md)
|
||||
|
||||
[GUIX Example](guix-example.md)
|
||||
|
||||
[Appendix A - GUIX Color Definitions](appendix-a.md)
|
||||
|
||||
[Appendix B - GUIX Color Formats](appendix-b.md)
|
||||
|
||||
[Appendix C - GUIX Widget Styles](appendix-c.md)
|
||||
|
||||
[Appendix D - GUIX Brush, Canvas and Gradient Attributes](appendix-d.md)
|
||||
|
||||
[Appendix E - GUIX Event Description](appendix-e.md)
|
||||
|
||||
[Appendix F - GUIX RTOS Binding Services](appendix-f.md)
|
||||
|
||||
[Appendix G - GUIX Font Structure](appendix-g.md)
|
||||
|
||||
[Appendix H - GUIX Build-Time Configuration flags](appendix-h.md)
|
||||
|
||||
[Appendix I - GUIX Information Structures](appendix-i.md)
|
||||
|
||||
[Appendix J - Canvas Partial Frame Buffer Feature](appendix-j.md)
|
||||
|
||||
## Guide Conventions
|
||||
|
||||
*Italics* - Typeface denotes book titles, emphasizes important words, and indicates variables.
|
||||
|
||||
**Boldface** - Typeface denotes file names, key words, and further emphasizes important words and variables.
|
||||
|
||||
> **Important:** Information symbols draw attention to important or additional information that could affect performance or function.
|
||||
|
||||
## GUIX Data Types
|
||||
|
||||
In addition to the custom GUIX control structure data types, there are several special data types that are used in GUIX service call interfaces. These special data types map directly to data types of the underlying C compiler. This is done to ensure portability between different C compilers. The exact implementation is inherited from ThreadX and can be found in the ***tx_port.h*** file included in the ThreadX distribution.
|
||||
|
||||
The following is a list of GUIX service call data types and their associated meanings:
|
||||
|
||||
| Data type | Description |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| **UINT** | Basic unsigned integer. This type is mapped to the most convenient unsigned data type. |
|
||||
| **INT** | Basic signed integer. This type is mapped to the most convenient signed data type. |
|
||||
| **ULONG** | Unsigned long type. This type must support 32-bit unsigned data. |
|
||||
| **VOID** | Almost always equivalent to the compiler's void type. |
|
||||
| **GX_CHAR** | Most often typedefed as the compiler defined char type. |
|
||||
| **GX_BYTE** | 8-bit signed type. |
|
||||
| **GX_UBYTE** | 8-bit unsigned type. |
|
||||
| **GX_VALUE** | 16 or 32 bit signed type. Defined as needed for best performance on the target system. |
|
||||
| **GX_FIXED_VAL** | Fixed point numeric data type. |
|
||||
| **GX_RESOURCE_ID** | Unsigned long type. |
|
||||
| **GX_COLOR** | Unsigned long type. |
|
||||
| **GX_STRING** | Structure containing GX_CHAR \*gx_string_ptr and UINT gx_string_length. |
|
||||
| **GX_POINT** | Structure containing gx_point_x and gx_point_y. |
|
||||
| **GX_RECTANGLE** | Structure containing gx_rectangle_left, gx_rectangle_top, gx_rectangle_right, and gx_rectangle_bottom fields. |
|
||||
| **GX_GLYPH** | Structure containing glyph metrics. |
|
||||
| **GX_FONT** | Structure containing font metrics. |
|
||||
| **GX_BRUSH** | Structure containing brush metrics. |
|
||||
**GX_PIXELMAP** | Structure containing pixelmap metrics.
|
||||
|
||||
Additional data types are used within the GUIX source. They are located in either the ***tx_port.h*** or ***gx_port.h*** files.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
For troubleshooting, capture the following information:
|
||||
|
||||
1. A detailed description of the problem, including frequency of occurrence and whether it can be reliably reproduced.
|
||||
|
||||
2. A detailed description of any changes to the application and/or GUIX that preceded the problem.
|
||||
|
||||
3. The contents of the _tx_version_id and _gx_version_id strings found in the ***tx_port.h*** and ***gx_port.h*** files of your distribution. These strings will provide valuable Information regarding your run-time environment.
|
||||
|
||||
4. The contents in RAM of the following ULONG variables:
|
||||
|
||||
**_tx_build_options**
|
||||
**_gx_system_build_options**
|
||||
|
||||
These variables will give information on how your ThreadX and GUIX libraries were built.
|
||||
|
||||
5. The contents in RAM of the following ULONG variables:
|
||||
|
||||
**_gx_system_last_error**
|
||||
**_gx_system_error_count**
|
||||
|
||||
These variables keep track of internal system errors in GUIX. If the _gx_system_error_count is greater than one, please set a breakpoint on the function return in the _gx_system_error_process function and find the value of _gx_system_last_error at this point. This will yield the first internal GUIX system error.
|
||||
|
||||
6. A trace buffer captured immediately after the problem was detected. This is accomplished by building the ThreadX and GUIX libraries with TX_ENABLE_EVENT_TRACE and calling tx_trace_enable with the trace buffer information.
|
||||
|
||||
7. The GUIX Studio project you are using, if applicable, or at a minimum a small project sufficient to demonstrate the deficiency.
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: Appendix A - GUIX Color Definitions
|
||||
description: Learn about the GUIX color definitions.
|
||||
---
|
||||
|
||||
# Appendix A - GUIX Color Definitions
|
||||
|
||||
__**Pre-defined color values**__
|
||||
|
||||
| Color | Value |
|
||||
| -------------------------------- | --------------- |
|
||||
| GX_COLOR_BLACK | 0xff000000 |
|
||||
| GX_COLOR_RED | 0xffb80000 |
|
||||
| GX_COLOR_GREEN | 0xff00bc00 |
|
||||
| GX_COLOR_BROWN | 0xffb8bc00 |
|
||||
| GX_COLOR_BLUE | 0xff0000b8 |
|
||||
| GX_COLOR_MAGENTA | 0xffb800b8 |
|
||||
| GX_COLOR_CYAN | 0xff00bcb8 |
|
||||
| GX_COLOR_LIGHTGRAY | 0xffc0c0c0 |
|
||||
| GX_COLOR_DARKGRAY | 0xff808080 |
|
||||
| GX_COLOR_LIGHTRED | 0xffff0000 |
|
||||
| GX_COLOR_LIGHTGREEN | 0xff00ff00 |
|
||||
| GX_COLOR_YELLOW | 0xffffff00 |
|
||||
| GX_COLOR_LIGHTBLUE | 0xff0000ff |
|
||||
| GX_COLOR_LIGHTMAGENTA | 0xffff00ff |
|
||||
| GX_COLOR_LIGHTCYAN | 0xff00ffff |
|
||||
| GX_COLOR_WHITE | 0xffffffff |
|
||||
|
||||
__**Pre-defined color IDs**__
|
||||
|
||||
| Color | Value |
|
||||
|---------------------------------- | ---- |
|
||||
| GX_COLOR_ID_CANVAS | 0 |
|
||||
| GX_COLOR_ID_WIDGET_FILL | 1 |
|
||||
| GX_COLOR_ID_WINDOW_FILL | 2 |
|
||||
| GX_COLOR_ID_DEFAULT_BORDER | 3 |
|
||||
| GX_COLOR_ID_WINDOW_BORDER | 4 |
|
||||
| GX_COLOR_ID_TEXT | 5 |
|
||||
| GX_COLOR_ID_SELECTED_TEXT | 6 |
|
||||
| GX_COLOR_ID_SELECTED_FILL | 7 |
|
||||
| GX_COLOR_ID_SHADOW | 8 |
|
||||
| GX_COLOR_ID_SHINE | 9 |
|
||||
| GX_COLOR_ID_BUTTON_BORDER | 10 |
|
||||
| GX_COLOR_ID_BUTTON_UPPER | 11 |
|
||||
| GX_COLOR_ID_BUTTON_LOWER | 12 |
|
||||
| GX_COLOR_ID_BUTTON_TEXT | 13 |
|
||||
| GX_COLOR_ID_SCROLL_FILL | 14 |
|
||||
| GX_COLOR_ID_SCROLL_BUTTON | 15 |
|
||||
| GX_COLOR_ID_TEXT_INPUT_TEXT | 16 |
|
||||
| GX_COLOR_ID_TEXT_INPUT_FILL | 17 |
|
||||
| GX_COLOR_ID_SLIDER_TICK | 18 |
|
||||
| GX_COLOR_ID_SLIDER_GROOVE_TOP | 19 |
|
||||
| GX_COLOR_ID_SLIDER_GROOVE_BOTTOM | 20 |
|
||||
| GX_COLOR_ID_SLIDER_NEEDLE_OUTLINE | 21 |
|
||||
| GX_COLOR_ID_SLIDER_NEEDLE_FILL | 22 |
|
||||
| GX_COLOR_ID_SLIDER_NEEDLE_LINE1 | 23 |
|
||||
| GX_COLOR_ID_SLIDER_NEEDLE_LINE2 | 24 |
|
||||
| GX_COLOR_ID_DISABLED_TEXT | 25 |
|
||||
| GX_COLOR_ID_DISABLED_FILL | 26 |
|
||||
| GX_COLOR_ID_READONLY_TEXT | 27 |
|
||||
| GX_COLOR_ID_READONLY_FILL | 28 |
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Appendix B - GUIX Color Formats
|
||||
description: Learn about the GUIX color formats.
|
||||
---
|
||||
|
||||
# Appendix B - GUIX Color Formats
|
||||
|
||||
| Color | Value |
|
||||
|------------------------------------ | ----- |
|
||||
| GX_COLOR_FORMAT_MONOCHROME | 1 |
|
||||
| GX_COLOR_FORMAT_MONOCHROME_INVERTED | 2 |
|
||||
| GX_COLOR_FORMAT_2BIT_4GRAY | 3 |
|
||||
| GX_COLOR_FORMAT_2BIT_GRAY_INVERTED | 4 |
|
||||
| GX_COLOR_FORMAT_4BIT_GRAY | 5 |
|
||||
| GX_COLOR_FORMAT_4BIT_GRAY_INVERTED | 6 |
|
||||
| GX_COLOR_FORMAT_4BIT_VGA | 7 |
|
||||
| GX_COLOR_FORMAT_8BIT_GRAY | 8 |
|
||||
| GX_COLOR_FORMAT_8BIT_GRAY_INVERTED | 9 |
|
||||
| GX_COLOR_FORMAT_8BIT_PALETTE | 10 |
|
||||
| GX_COLOR_FORMAT_8BIT_PACKED_PIXEL | 11 |
|
||||
| GX_COLOR_FORMAT_15BIT_BGR | 12 |
|
||||
| GX_COLOR_FORMAT_15BIT_RGB | 13 |
|
||||
| GX_COLOR_FORMAT_16BIT_RGB | 14 |
|
||||
| GX_COLOR_FORMAT_16BIT_ARGB | 15 |
|
||||
| GX_COLOR_FORMAT_16BIT_BGRA | 16 |
|
||||
| GX_COLOR_FORMAT_16BIT_BGR | 17 |
|
||||
| GX_COLOR_FORMAT_24BIT_RGB | 18 |
|
||||
| GX_COLOR_FORMAT_24BIT_BGR | 19 |
|
||||
| GX_COLOR_FORMAT_24BIT_XRGB | 20 |
|
||||
| GX_COLOR_FORMAT_24BIT_BGRX | 21 |
|
||||
| GX_COLOR_FORMAT_32BIT_ARGB | 22 |
|
||||
| GX_COLOR_FORMAT_32BIT_RGBA | 23 |
|
||||
| GX_COLOR_FORMAT_32BIT_ABGR | 24 |
|
||||
| GX_COLOR_FORMAT_32BIT_BGRA | 25 |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Appendix D - GUIX Brush, Canvas and Gradient Attributes
|
||||
description: Learn about the GUIX brush, canvas and gradient attributes.
|
||||
---
|
||||
|
||||
# Appendix D - GUIX Brush, Canvas and Gradient Attributes
|
||||
|
||||
__**Brush Styles:**__
|
||||
|
||||
**GX_BRUSH_OUTLINE**
|
||||
- Value: 0x0000
|
||||
- Description: This brush style applies to shape drawing functions such as gx_canvas_rectangle_draw or gx_canvas_polygon_draw. This style indicates the shape should be outlined, in addition to optionally being filled. If the GX_BRUSH_OUTLINE style is set and the GX_BRUSH_SOLID_FILL is cleared, the shape is only outlined.
|
||||
|
||||
**GX_BRUSH_SOLID_FILL**
|
||||
- Value: 0x0001
|
||||
- Description: This brush style applies to shape drawing functions, and indicates that the requested shape should be filled with a solid color using the current brush fill color.
|
||||
|
||||
**GX_BRUSH_PIXELMAP_FILL**
|
||||
- Value: 0x0002
|
||||
- Description: This brush style applies to shape drawing functions, and indicates that the requested shape should be pattern filled with the current brush pixelmap.
|
||||
|
||||
**GX_BRUSH_ALIAS**
|
||||
- Value: 0x0004
|
||||
- Description: This brush style applies to all line drawing and shape outlines. If this flag is set, lines and outlines are drawing with the more accurate but also more time consuming anti-aliased drawing algorithms. This style flag is only used for 16-bpp color depths and higher.
|
||||
|
||||
**GX_BRUSH_UNDERLINE**
|
||||
- Value: 0x0008
|
||||
- Description: This flag applies to text drawing, and indicates that subsequent text drawn should be underlined.
|
||||
|
||||
**GX_BRUSH_ROUND**
|
||||
- Value: 0x0010
|
||||
- Description: This flag applies to line drawing, and indicates that line ends are drawn with a round or circular shape, rather than the default square shape.
|
||||
|
||||
__**Canvas Flags:**__
|
||||
|
||||
**GX_CANVAS_SIMPLE**
|
||||
- Value: 0x01
|
||||
- Description: A memory canvas which is used to off-screen drawing.
|
||||
|
||||
**GX_CANVAS_MANAGED**
|
||||
- Value: 0x02
|
||||
- Description: A canvas which automatically flushed to the active display, either as part of the composite building process or as part of the buffer toggle operation for single-canvas architectures.
|
||||
|
||||
**GX_CANVAS_VISIBLE**
|
||||
- Value: 0x04
|
||||
- Description: This flag can be used to turn on and off a canvas, without losing the canvas drawing contents.
|
||||
|
||||
**GX_CANVAS_MODIFIED**
|
||||
- Value: 0x08
|
||||
- Description: Reserved for future use.
|
||||
|
||||
**GX_CANVAS_COMPOSITE**
|
||||
- Value: 0x20
|
||||
- Description: This flag is used by the application when configuring a multiple-canvas system which will composite multiple managed canvases into the composite canvas, and the composite is the driven to the hardware frame buffer.
|
||||
|
||||
__**Gradient Types:**__
|
||||
|
||||
**GX_GRADIENT_TYPE_VERTICAL**
|
||||
- Value: 0x01
|
||||
- Description: Creates a vertical alphamap gradient.
|
||||
|
||||
**GX_GRADIENT_TYPE_ALPHA**
|
||||
- Value: 0x02
|
||||
- Description: Creates an alpha-map style gradient. This is currently the only gradient style supported.
|
||||
|
||||
**GX_GRADIENT_TYPE_MIRROR**
|
||||
- Value: 0x04
|
||||
- Description: This flag indicates that the gradient should peak at the center of the width/height range, and return to the starting value as it reaches the right/bottom edge. Without this style flag, the gradient will be a linear gradient from top-to-bottom or left-to-right, depending on the GX_GRADIENT_TYPE_VERTICAL flag.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: Appendix F - GUIX RTOS Binding Services
|
||||
description: Learn about GUIX RTOS binding services.
|
||||
---
|
||||
|
||||
# Appendix F - GUIX RTOS Binding Services
|
||||
|
||||
GUIX requires thread or tasking services, mutex, event queue, and timing services providing by the underlying RTOS. By default GUIX is configured to utilize the ThreadX real time operating system to provide these services. To port GUIX to another operating system, the developer should # define the pre-processor directive GX_DISABLE_THREADX_BINDING and rebuild the GUIX library to remove the ThreadX dependencies. In addition, the developer will need to provide the following macro
|
||||
definitions and supporting functions. Examples of these macro definitions and supporting functions can be found in the files gx_system_rtos_bind.h and gx_system_rtos_bind.c, which provide an
|
||||
example generic rtos integration.
|
||||
|
||||
System Integration macros:
|
||||
|
||||
**GX_RTOS_BINDING_INITIALIZE**
|
||||
|
||||
This macro is invoked during system initialization. The macro should be defined to call any function needed to prepare your rtos system services or rtos resources prior to use. This is the binding's opportunity to prepare the rtos resources that GUIX will use.
|
||||
|
||||
**GX_SYSTEM_THREAD_START**
|
||||
|
||||
This macro is invoked when the GUIX task or thread should start executing. This macro should be defined to call a function which will start the GUIX thread running. The entry point to the GUIX thread is passed to the called function. The signature of the called function must be
|
||||
|
||||
**UINT *function_name*(VOID (thread_entry_point)(VOID));**
|
||||
|
||||
This function should return GX_SUCCESS if the thread is successfully started, or GX_FAILURE.
|
||||
|
||||
**GX_EVENT_PUSH**
|
||||
|
||||
This macro is invoked to push an event into the FIFO event queue used by GUIX. When porting to a new rtos, it is your responsibility to implement this event queue in a thread-safe manner. GX_EVENT structures must be copied into this queue and copied out of this queue, i.e. a queue of GX_EVENT pointers will not work, since GUIX events can be automatic variables from the view of the event producer. The signature of the function called by this macro must be:
|
||||
|
||||
**UINT *function_name* (GX_EVENT *event_ptr);**
|
||||
|
||||
This function should return GX_SUCCESS if the event is pushed into the event queue, otherwise it should return GX_FAILURE.
|
||||
|
||||
**GX_EVENT_POP**
|
||||
|
||||
This macro is invoked to remove the head (oldest) event from the GUIX event queue and copy it into the requested location. This function must be able to optionally block or wait for an event if no events are currently in the event queue. The signature of the function invoked by this macro must be
|
||||
|
||||
UINT function_name(GX_EVENT *put_event, GX_BOOL wait)
|
||||
|
||||
If the wait parameter == GX_TRUE, the function should not return until an event is provided. If the wait parameter is GX_FALSE, the function should return immediately with or without an event.
|
||||
|
||||
If an event is retrieved from the queue, it should copied into the put_event location and the return status is GX_SUCCESS. Otherwise the return status should be GX_FAILURE.
|
||||
|
||||
**GX_EVENT_FOLD**
|
||||
|
||||
This macro is invoked by GUIX to fold an event into the FIFO event queue. Folding an event means that if an event of the same type already exists in the queue, that entry is update to contain the payload of the new event. If an existing event of the same type is not found in the queue, a new event is pushed into the queue.
|
||||
|
||||
For bindings that cannot implement the event fold feature, it is acceptable to simply invoke the GX_EVENT_PUSH.
|
||||
|
||||
**GX_TIMER_START**
|
||||
|
||||
This macro is invoked when GUIX needs to receive periodic timer input. This macro should invoke a service that starts the low-level RTOS periodic timer service. If the RTOS timer service cannot be easily stopped and started, it is acceptable but less efficient to leave this service running at all times.
|
||||
|
||||
When the low-level RTOS timer service periodically expires, the binding must call the GUIX system function _gx_system_timer_expiration(0); Calling this function periodically is what drives the high-level GUIX timer widget timer services.
|
||||
|
||||
**GX_TIMER_STOP**
|
||||
|
||||
This macro is invoked when GUIX no longer needs a periodic timer (i.e. there are no active GUIX timers running). If the RTOS timer service cannot be easily stopped and started, it is acceptable but less efficient to leave this service running at all times and define this
|
||||
macro to do nothing.
|
||||
|
||||
**GX_SYSTEM_MUTEX_LOCK**
|
||||
|
||||
This macro is invoked by GUIX during critical code sections to prevent another task from pre-empting and modifying common data structures, potentially causing corruption. This macro should call a function that implements the suitable RTOS resource locking service.
|
||||
|
||||
If you never utilize any GUIX API services outside of the GUIX thread, you can define this macro to do nothing.
|
||||
|
||||
**GX_SYSTEM_MUTEX_UNLOCK**
|
||||
|
||||
This macro is invoked at the end of critical code sections, and should unlock the GUIX resource using the suitable underlying RTOS service. If you never utilize any GUIX API services outside of the GUIX thread, you can define this macro to do nothing.
|
||||
|
||||
**GX_SYSTEM_TIME_GET**
|
||||
|
||||
This macro should call a function that returns the current system time is "system ticks", which is usually the number of low-level timer interrupts that have occurred since system startup. This service is used to calculate touch event pen speed for touch input gestures. The signature of the function invoked by this macro must be:
|
||||
|
||||
**ULONG *function_name*(VOID);**
|
||||
|
||||
**GX_CURRENT_THREAD**
|
||||
|
||||
This macro is invoked to identify the currently executing thread. The service called by this macro must return a void *, meaning that the data type used by your operating system to identify the current execution thread must be cast to a void * to be returned to GUIX.
|
||||
|
||||
A complete example of a generic RTOS binding is implemented in the files gx_system_rtos_bind.h and gx_system_rtos_bind.c
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: Appendix G - GUIX Font Structure
|
||||
description: Learn about the GUIX font structure.
|
||||
---
|
||||
|
||||
# Appendix G - GUIX Font Structure
|
||||
|
||||
GUIX fonts are normally produced by the GUIX Studio application, and font glyphs are rendered by the GUIX display driver. The application software need only specify the font and colors that each text display widget should use. The GUIX font data structures are documented here for completeness, and to enable developers to create their own methods for generating or converting other fonts into the GUIX font format.
|
||||
|
||||
Each GUIX font starts with a GX_FONT structure. The GX_FONT structure defines global font parameters, such as the character included within the font and the line height of the font. The GX_FONT structure points at an array of GX_GLYPH structures. Each GX_GLYPH structure defines
|
||||
the width, height, and baseline offset of one specific character glyph. The GX_GLYPH structure also points to the actual glyph bitmap data (which may be NULL for whitespace characters).
|
||||
|
||||
The **GX_FONT** structure, contained in gx_api.h, is declared as follows:
|
||||
|
||||
```c
|
||||
typedef struct GX_FONT_STRUCT
|
||||
{
|
||||
GX_UBYTE gx_font_format
|
||||
GX_UBYTE gx_font_prespace
|
||||
GX_UBYTE gx_font_postspace
|
||||
GX_UBYTE gx_font_line_height
|
||||
GX_UBYTE gx_font_baseline
|
||||
USHORT gx_font_first_glyph
|
||||
USHORT gx_font_last_glyph
|
||||
GX_CONST GX_GLYPH *gx_font_glyphs
|
||||
const struct GX_FONT_STRUCT *gx_font_next_page
|
||||
} GX_FONT;
|
||||
```
|
||||
|
||||
The *gx_font_format* field defines the font bits-per-pixel and other flags, as defined in the gx_api.h header file.
|
||||
|
||||
The *gx_font_prespace* defines the pixel space to skip above each line of text in a multi-line text display.
|
||||
|
||||
The *gx_font_postspace* field defines the pixel space to skip below each line of text in a multi-line text display.
|
||||
|
||||
The *gx_font_line_height* field defines the height of the tallest glyph in the font.
|
||||
|
||||
The *gx_font_baseline* field defines the distance, in pixels, from the top row of glyph pixels to the font baseline.
|
||||
|
||||
The *gx_font_first_glyph* field defines the first Unicode character encoding included in this font page.
|
||||
|
||||
The *gx_font_last_glyph* field defines the last Unicode character encoding included in this font page.
|
||||
|
||||
The *gx_font_glyphs* pointer points to an array of GX_GLYPH structures. This array must be equal in size to the number of characters contained on this font page, i.e (*gx_font_last_glyph* – *gx_font_first_glyph*) + 1.
|
||||
|
||||
The *gx_font_next_page* member is used for multiple page fonts. Multiple page fonts are used for extended character sets and to optimize the size of the GX_GLYPH structure arrays. If all of the characters of the font are contained within one font page, or if this is the last page of the font in question, the *gx_font_next_page* member is set to GX_NULL.
|
||||
|
||||
As noted above, the **GX_FONT** structure above contains a pointer to an array of GX_GLYPHS structures. There must be one GX_GLYPH structure for each character on the font page. The **GX_GLYPH** structure is defined as:
|
||||
|
||||
```c
|
||||
typedef struct GX_GLYPH_STRUCT
|
||||
{
|
||||
GX_CONST GX_UBYTE *gx_glyph_map;
|
||||
GX_BYTE gx_glyph_ascent;
|
||||
GX_BYTE gx_glyph_descent;
|
||||
GX_BYTE gx_glyph_advance;
|
||||
GX_BYTE gx_glyph_leading;
|
||||
GX_UBYTE gx_glyph_width;
|
||||
GX_UBYTE gx_glyph_height;
|
||||
} GX_GLYPH;
|
||||
```
|
||||
|
||||
The gx_glyph_map pointer points to the glyph bitmap. This pointer may be GX_NULL for whitespace characters. The bitmap data is encoded as 1 bpp, 2 bpp, 4 bpp, or 8 bpp alpha values. For 1 bit data, a value of 1 indicates that the pixel should be written in the foreground color, and a value of 0 indicates that the pixel is transparent. For 8 bit data, the values range from 0 (fully transparent) to 255 (fully opaque). All intermediate values represent a blending value for anti-aliased fonts. The glyph bitmap data is always padded to full byte alignment for formats using less than 8bpp data values.
|
||||
|
||||
The *gx_glyph_ascent* and gx_glyph_descent values position the glyph vertically with respect to the font baseline.
|
||||
|
||||
The *gx_glyph_width* and gx_glyph_height values specify the size of the glyph bitmap data.
|
||||
|
||||
The *gx_glyph_advance* value specifies the pixel width to advance the drawing position after drawing the glyph (this may not be equal to the glyph width).
|
||||
|
||||
The *gx_glyph_leading* value specifies the pixels to advance in the x-direction prior to rendering the glyph.
|
||||
@@ -0,0 +1,152 @@
|
||||
---
|
||||
title: Appendix H - GUIX Build-Time Configuration flags
|
||||
description: Learn about GUIX build-time configuration flags.
|
||||
---
|
||||
|
||||
# Appendix H - GUIX Build-Time Configuration flags
|
||||
|
||||
GUIX support several conditional compilation options and configuration values. The default setting for these conditionals and configuration values can be overridden by pre-defining the value, either in your gx_user.h header file or on your compiler command line.
|
||||
|
||||
**GX_DISABLE_THREADX_BINDING**
|
||||
- Default: Undefined
|
||||
- Description: This conditional can be used to disable the default ThreadX RTOS binding. If you want to run GUIX with an RTOS other than ThreadX, you should #define GX_DISABLE_THREADX_BINDING and provide your own RTOS binding services.
|
||||
|
||||
**GX_SYSTEM_TIMER_MS**
|
||||
- Default: 20
|
||||
- Description: This value defines the desired GUIX timer interval or precision.
|
||||
|
||||
**TX_TIMER_TICKS_PER_SECOND**
|
||||
- Default: 100
|
||||
- Description: This value defines the number of TX timer interrupt frequencies. Since the default ThreadX interval timer is 10 ms, this value defaults to a 100-Hz frequency.
|
||||
|
||||
**GX_DISABLE_MULTITHREAD_SUPPORT**
|
||||
- Default: Not defined
|
||||
- Description: This compile-time conditional can be used to disable the GUIX API support for multiple threads invoking the GUIX API concurrently. If only one application thread will ever utilize the GUIX API, you should define this flag to reduce the system overhead associated with protecting critical code sections.
|
||||
|
||||
**GX_DISABLE_UTF8_SUPPORT**
|
||||
- Default: Not Defined.
|
||||
- Description: This compile-time conditional can be used to remove the GUIX internal support for UTF8 format string encoding. If you are using only character values M- 0xff in your application, turning on this #define will reduce the code size and overhead associated with supporting UTF8 format string encoding.
|
||||
|
||||
**GX_DISABLE_ARC_DRAWING_SUPPORT**
|
||||
- Default: Not defined.
|
||||
- Description: This conditional can be used to reduce the GUIX library code size and GX_DISPLAY structure size by removing support for the arc-drawing functions circle, arc, pie, and ellipse. These functions are not required by the default GUIX widget set.
|
||||
|
||||
**GX_DISABLE_SOFTWARE_DECODER_SUPPORT**
|
||||
- Default: Not defined.
|
||||
- Description: This conditional can be defined to remove the GUIX library runtime jpeg and png software decoder support. If your application does not require runtime decode of jpg or png files meaning your application does not use RAW format pixelmaps produced by Studio and does not read image files from an external filesystem, you can turn on this #define to reduce the GUIX library footprint.
|
||||
|
||||
**GX_DISABLE_BINARY_RESOURCE_SUPPORT**
|
||||
- Default: Not defined
|
||||
- Description: This conditional can be used to remove the GUIX library support for loading binary resource data. Binary resources can be used to do runtime binding of resource data with your GUIX application. If you are using only C source code format resource files, you can define this conditional to reduce your GUIX library footprint.
|
||||
|
||||
**GX_DISABLE_BRUSH_ALPHA_SUPPORT**
|
||||
- Default: Not defined.
|
||||
- Description: When running at 16 bpp and higher color depths, GUIX optionally supports drawing non-arc graphics, pixelmaps, and fonts with an alpha value defined by the drawing context brush. Supporting this drawing mode introduces a small runtime overhead and library footprint increase, which can be eliminated by defining this flag if you do not require alpha-blending drawing support. Note that pixelmaps with alpha channel, anti-aliased fonts, and other anti-aliasing drawing modes are still supported regardless of this conditional setting.
|
||||
|
||||
**GX_DISABLE_THREADX_TIMER_SOURCE**
|
||||
- Default: Not defined.
|
||||
- Description: This conditional can be used to disable the ThreadX timer source. You should define GX_DISABLE_THREADX_TIMER_SOURCE if you want to use a different timer source.
|
||||
|
||||
**GX_ENABLE_ARM_HELIUM**
|
||||
- Default: Not defined.
|
||||
- Description: This conditional can be used to enable ARM Helium instructions for JPEG decoding, resulting in enhanced performance.
|
||||
|
||||
**GX_ENABLE_CANVAS_PARTIAL_FRAME_BUFFER**
|
||||
- Default: Not defined.
|
||||
- Description: This conditional can be used to enable partial frame buffer support for canvas. When this conditional is defined, you are able to define a canvas buffer that is smaller than the canvas size. This is useful when the system has limited memory.
|
||||
|
||||
**GX_CANVAS_REFRESH_DIRECTION_HORIZONTAL**
|
||||
- Default: Not defined.
|
||||
- Description: This conditional is used when canvas partial frame buffer feature is enabled. This conditional can be used to enable horizontal refresh direction for canvas, specifically from left to right.
|
||||
|
||||
**GX_CANVAS_REFRESH_DIRECTION_VERTICAL**
|
||||
- Default: Not defined.
|
||||
- Description: This conditional is used when canvas partial frame buffer feature is enabled. This conditional can be used to enable vertical refresh direction for canvas, specifically from top to bottom.
|
||||
|
||||
**GX_REPEAT_BUTTON_INITIAL_TICS**
|
||||
- Default: 10.
|
||||
- Description: If a button has style GX_STYLE_BUTTON_REPEAT, this value defines how long the button
|
||||
waits before beginning to send repeated GX_EVENT_CLICKED events.
|
||||
|
||||
**GX_MAX_QUEUE_EVENTS**
|
||||
- Default: 48.
|
||||
- Description: Defines the size of the GUIX event queue in units of event structure entries. If the event queue overflows, events being pushed into the queue are discarded and GX_SYSTEM_ERROR is returned by the gx_system_event_send() function.
|
||||
|
||||
**GX_MAX_DIRTY_AREAS**
|
||||
- Default: 64.
|
||||
- Description: Defines the maximum number of unique dirty list entries that can be maintained by one canvas. When the dirty list overflows, GUIX will default to marking the canvas root window as dirty, which is less efficient than drawing individual child widgets.
|
||||
|
||||
**GX_MAX_CONTEXT_NESTING**
|
||||
- Default: 8.
|
||||
- Description: Defines the maximum nesting of the drawing context stack. This is equivalent to the maximum nesting of parent/child/child/child widgets within the UI definition.
|
||||
|
||||
**GX_MAX_INPUT_CAPTURE_NESTING**
|
||||
- Default: 4.
|
||||
- Description: Defines the size of the stack used to maintain the list of widgets that have captures the user input (mouse and keyboard).
|
||||
|
||||
**GX_SYSTEM_THREAD_PRIORITY**
|
||||
- Default: 16.
|
||||
- Description: Defines the priority of the GUIX thread created during gx_system_initialize().
|
||||
|
||||
**GX_SYSTEM_THREAD_TIMESLICE**
|
||||
- Default: 10.
|
||||
- Description: Defines the GUIX thread timeslice in terms of RTOS timer ticks. If other threads are defined with the same priority as the GUIX thread, this value determines how often those competing threads are granted CPU control.
|
||||
|
||||
**GX_CURSOR_BLINK_INTERVAL**
|
||||
- Default: 20.
|
||||
- Description: Defines the rate at which the input cursor blinks for text input widgets. This value is in terms of GUIX timer ticks, which by default is defines as 50 ms, so a value of 20 indicates that the input cursor blinks once per second.
|
||||
|
||||
**GX_MULTI_LINE_INDEX_CACHE_SIZE**
|
||||
- Default: 32.
|
||||
- Description: Defines the size of the list-start index cache maintained by the multi-line text view and multi-line text input widgets. This cache is used to accomplish fast vertical scrolling of multi line text widgets. For best performance, the cache size should be set greater than the number of visible rows of the largest multi line text widget defined by the application. For example, if the most visible rows for any text widget are 20 rows, the application might define a cache size
|
||||
of 32 (the default), which allows GUIX to scroll vertically without recalculating all line start indexes.
|
||||
|
||||
**GX_MULTI_LINE_TEXT_BUTTON_MAX_LINES**
|
||||
- Default: 4.
|
||||
- Description: The multi-line text button control block maintains a pointer to each line of text to be displayed by the button. This value determines the number of text pointers needed by the worst case multi-line text button.
|
||||
|
||||
**GX_POLYGON_MAX_EDGE_NUM**
|
||||
- Default: 10.
|
||||
- Description: This value determines the most complex polygon that can be drawn by GUIX. The polygon drawing algorithm determines the lines needed to define the polygon edges, and this definition defines the maximum number of edges that can be supported.
|
||||
|
||||
**GX_NUMERIC_SCROLL_WHEEL_STRING_BUFFER_SIZE**
|
||||
- Default: 16.
|
||||
- Description: For a number scroll wheel, the scroll wheel widget converts integer values to ascii strings. This value determines the maximum length of the string required to display the assigned integer values.
|
||||
|
||||
**GX_DEFAULT_CIRCULAR_GAUGE_ANIMATION_DELAY**
|
||||
- Default: 5.
|
||||
- Description: Defines the number of GUIX timer ticks (50 ms) between updates of a circular gauge configured to animate the needle movement between last and current angular position.
|
||||
|
||||
**GX_NUMERIC_PROMPT_BUFFER_SIZE**
|
||||
- Default: 16.
|
||||
- Description: A numeric prompt allocates a buffer to convert an integer value assigned to the prompt to an ascii string. This definition defines the size of this character buffer.
|
||||
|
||||
**GX_ANIMATION_POOL_SIZE**
|
||||
- Default: 6.
|
||||
- Description: GUIX defines an animation pool from which animation information structures can be dynamically allocated and returned, using gx_system_animation_get and gx_system_animation_free()
|
||||
APIs. This definition defines the size of this animation control block pool.
|
||||
|
||||
**GX_MOUSE_SUPPORT**
|
||||
- Default: Not defined.
|
||||
- Description: This definition enables support for mouse input. Software mouse requires that the display driver draw and track the mouse cursor, which adds extra overhead to the display driver. This definition should only be defined when a mouse (not a touch screen) must be supported.
|
||||
|
||||
**GX_HARDWARE_MOUSE_SUPPORT**
|
||||
- Default: Not defined.
|
||||
- Description: When this definition is defined, the GUIX display driver utilizes hardware mouse cursor drawing support. This reduces the memory required to capture the canvas memory beneath the mouse cursor and improves system performance for those hardware targets support a mouse overlay graphics layer.
|
||||
|
||||
**GX_FONT_KERNING_SUPPORT**
|
||||
- Default: Not defined.
|
||||
- Description: This definition can be defined to enable font kerning support. Font kerning improves glyph spacing for certain glyph combinations. This support adds a small amount of overhead to the
|
||||
runtime string drawing functions, and also adds a small amount of size to the font data structures.
|
||||
|
||||
**GX_WIDGET_USER_DATA**
|
||||
- Default: Not defined.
|
||||
- Description: If defined, this adds a user-defined data field to the GX_WIDGET control block. This data field can be assigned using the properties view within GUIX Studio. This data field is ignored by GUIX internally, but can be used by application software for many purposes.
|
||||
|
||||
**GUIX_5_4_0_COMPATIBILITY**
|
||||
- Default: Not defined.
|
||||
- Description: Certain GUI APIs were modified after release 5.4.0 to add support for disabled text colors and to improve the accuracy of certain math functions by using fixed-point match parameters. These changes make GUIX library releases after 5.4.0 incompatible with previous releases. However, by turning on this #define, the library can be built such that the APIs fully compatible with releases <= 5.4.0, meaning that no changes are needed in existing applications to compile with the latest GUIX library release.
|
||||
|
||||
**GX_MAX_STRING_LENGTH**
|
||||
- Default: 102400
|
||||
- Description: Defines the maximum length of a string, which is used to test invalid strings. If the input string is exceeding the maximum string length, it will be regard as invalid.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Appendix D - Canvas Partial Frame Buffer Feature
|
||||
description: Learn about the GUIX canvas partial frame buffer feature.
|
||||
---
|
||||
|
||||
# Appendix J - Canvas Partial Frame Buffer Feature
|
||||
|
||||
The canvas partial frame buffer feature allows you to allocate a smaller portion of memory for the canvas buffer compared to the full canvas size. This is particularly advantageous for embedded systems with limited memory. This feature is disabled by default and only available for 565rgb color format without screen rotation. To enable this feature, you must define the configuration GX_ENABLE_CANVAS_PARTIAL_FRAME_BUFFER.
|
||||
|
||||
The minimum canvas memory size should be sufficient to accommodate a single line of pixels on the screen.
|
||||
|
||||
### Example to enable the canvas partial frame buffer feature
|
||||
|
||||
- Define the configuration GX_ENABLE_CANVAS_PARTIAL_FRAME_BUFFER.
|
||||
- Uncheck "allocate canvas memory" in project configure dialog for your GUIX Studio project and generate output files.
|
||||
- Call `gx_canvas_memory_define` to allocate canvas memory.
|
||||
- Update your toggle function. The following example shows how to update the toggle function for the canvas partial frame buffer feature.
|
||||
```
|
||||
void hardware_16bpp_buffer_toggle(GX_CANVAS *canvas, GX_RECTANGLE *dirty)
|
||||
{
|
||||
|
||||
GX_RECTANGLE Limit;
|
||||
GX_RECTANGLE Copy;
|
||||
INT y;
|
||||
USHORT* pixel;
|
||||
|
||||
|
||||
USHORT *memptr = (USHORT*)canvas -> gx_canvas_memory;
|
||||
|
||||
gx_utility_rectangle_define(&Limit, 0, 0,
|
||||
BOARD_SCREEN_WIDTH - 1, BOARD_SCREEN_HEIGHT - 1);
|
||||
|
||||
if (gx_utility_rectangle_overlap_detect(&Limit, &canvas->gx_canvas_dirty_area, &Copy))
|
||||
{
|
||||
for(y = Copy.gx_rectangle_top; y <= Copy.gx_rectangle_bottom; y++)
|
||||
{
|
||||
pixel = memptr;
|
||||
|
||||
#if defined(GX_ENABLE_CANVAS_PARTIAL_FRAME_BUFFER)
|
||||
pixel += (y - canvas->gx_canvas_memory_offset_y) * canvas->gx_canvas_memory_width;
|
||||
pixel += (Copy.gx_rectangle_left - canvas->gx_canvas_memory_offset_x);
|
||||
#else
|
||||
pixel += y * BOARD_SCREEN_WIDTH;
|
||||
pixel += Copy.gx_rectangle_left;
|
||||
#endif
|
||||
|
||||
BSP_LCD_DrawRGBImage(Copy.gx_rectangle_left, y, Copy.gx_rectangle_right - Copy.gx_rectangle_left + 1, 1, (uint8_t *)pixel);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Canvas Refresh Methods for Partial Frame Buffer Feature
|
||||
|
||||
GUIX manages the canvas dirty area using a linked list. By default, the canvas refreshes its dirty areas by iterating through the dirty list and refreshing each dirty area sequentially. This approach optimizes the utilization of available canvas memory. However, this method does not guarantee a specific refresh direction, which can make it challenging to effectively mitigate potential tearing effects.
|
||||
|
||||
|
||||
|
||||
*Figure 1: Tearing Effect Example.*
|
||||
|
||||
Let's consider Figure 1 as an example to illustrate how tearing effect happens. In this scenario, the canvas exhibits two dirty areas labeled as "Dirty 1" and "Dirty 2." The red horizontal line represents the display refreshing line.
|
||||
|
||||
The canvas undertakes the task of refreshing the dirty areas in the sequence of "Dirty 1" followed by "Dirty 2." Assuming the display refreshes from top to bottom, the process unfolds as follows: When the display refreshes line 1, the canvas initiates the refreshing of its dirty area. By the time the display refresh reaches line 2, "Dirty 1" has been updated. When the display refresh advances to line 3, "Dirty 2" is updated as well.
|
||||
|
||||
However, upon reaching the bottom, only the updated portion of "Dirty 1" is displayed on the screen, while the updated portion of "Dirty 2" is yet to be displayed. This disparity between the two areas may cause the undesirable tearing effect.
|
||||
|
||||
To address the previously mentioned issues, two additional canvas refresh methods are made available. You can enable one of these methods using either of the following two definitions:
|
||||
- GX_CANVAS_REFRESH_DIRECTION_VERTICAL
|
||||
- GX_CANVAS_REFRESH_DIRECTION_HORIZONTAL
|
||||
|
||||
#### Canvas Refresh Direction: Vertical
|
||||
|
||||
When the canvas refresh direction is set to vertical, the canvas refreshes its dirty areas in the vertical direction.
|
||||
|
||||
|
||||
|
||||
*Figure 2: Canvas Refreshing with Direction Set to Vertical.*
|
||||
|
||||
Figure 2 illustrates the canvas refreshing process with the direction set to vertical. In this configuration, a combined dirty area is calculated, encompassing both "Dirty 1" and "Dirty 2," represented by the dashed black rectangle. A mask window is employed, matching the width of the combined dirty area, with the total mask size matching the available canvas size. This mask window is moved vertically from the top to the bottom within the combined dirty area, updating the dirty area located within the mask window.
|
||||
|
||||
There can still be tearing effect in this refreshing method. To eliminate the tearing effect, additional work is necessary. For example, if the display refreshing speed is faster than the canvas refreshing speed, while the display refreshing pass the top of the combined refreshing area, the canvas can start refreshing, but the display won't show the updated content until the next refreshing pass. This can eliminate the possible tearing effect.
|
||||
|
||||
### Canvas Refresh Direction: Horizontal
|
||||
|
||||
When the canvas refresh direction is set to horizontal, the canvas refreshes its dirty areas in the horizontal direction.
|
||||
|
||||
|
||||
|
||||
*Figure 3: Canvas Refreshing with Direction Set to Horizontal.*
|
||||
|
||||
Figure 3 illustrates the canvas refreshing process with the direction set to horizontal. In this configuration, a combined dirty area is calculated, encompassing both "Dirty 1" and "Dirty 2," represented by the dashed black rectangle. A mask window is employed, matching the height of the combined dirty area, with the total mask size matching the available canvas size. This mask window is moved horizontally from the left to the right within the combined dirty area, updating the dirty area located within the mask window.
|
||||
|
||||
There can still be tearing effect in this refreshing method. To eliminate the tearing effect, additional work is required. For example, if the display refreshing speed is faster than the canvas refreshing speed, while the display refreshing pass the left of the combined refreshing area, the canvas can start refreshing, but the display won't show the updated content until the next refreshing pass. This eliminates the tearing effect.
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
title: Chapter 1 - Introduction to GUIX
|
||||
description: GUIX is a high-performance real-time implementation of a GUI designed exclusively for embedded ThreadX-based applications.
|
||||
---
|
||||
|
||||
# Chapter 1 - Introduction to GUIX
|
||||
|
||||
GUIX is a high-performance real-time implementation of a graphical interface framework designed
|
||||
exclusively for embedded ThreadX-based applications. This chapter
|
||||
contains an introduction to GUIX and a description of its applications
|
||||
and benefits.
|
||||
|
||||
## GUIX Feature Overview
|
||||
|
||||
Unlike many other GUI implementations, GUIX is designed to be versatile—easily scaling from small micro-controller-based applications to those that use powerful RISC and DSP processors. This is in sharp contrast to public domain or other commercial implementations originally intended for workstation environments but then squeezed into
|
||||
embedded designs. An overview of GUIX features follows:
|
||||
|
||||
- Easy to use with host-based design tool GUIX Studio
|
||||
|
||||
- Win32 GUIX run-time environment for complete hosted prototyping
|
||||
|
||||
- Supports most processors supported by ThreadX
|
||||
|
||||
- Written exclusively in ANSI C
|
||||
|
||||
- Endian neutral
|
||||
|
||||
- Smallest, Fasted Embedded GUI
|
||||
|
||||
- Run-time configurable, number of objects, screen size, etc.
|
||||
|
||||
- Easy to write display driver interface
|
||||
|
||||
- Color (up to 32-bpp color depth), monochrome, and grayscale support
|
||||
|
||||
- Multilingual support via UTF8 string encoding and string resources
|
||||
|
||||
- Default free fonts and easy to add new fonts
|
||||
|
||||
- Multiple drawing Canvases supported, of various sizes
|
||||
|
||||
- Multiple displays of different sizes and color depths supported
|
||||
|
||||
- Screen Transition support (fade in, fade out, swipe, etc.)
|
||||
|
||||
- Touch Screen, Gesture, and Virtual Keyboard Support
|
||||
|
||||
- Bitmap compression
|
||||
|
||||
- Alpha Blending Support
|
||||
|
||||
- Dither Support
|
||||
|
||||
- Anti-Aliasing Support
|
||||
|
||||
- Skinning and Themes
|
||||
|
||||
- Canvas Blending
|
||||
|
||||
- Complete Window Management
|
||||
|
||||
- Parent/Child Relationship
|
||||
|
||||
- Dynamic creation, deletion, resizing, moving
|
||||
- Separate event handling and drawing
|
||||
- Z-order
|
||||
- Clipping and views
|
||||
|
||||
- Extensive Set of Widgets
|
||||
|
||||
- Various button types, sliders, and dials
|
||||
|
||||
- Drop Down List
|
||||
|
||||
- Prompt
|
||||
|
||||
- Multi-Line text view
|
||||
|
||||
- Single and Multi-Line text input
|
||||
|
||||
- Numeric and Textual Scroll Wheels
|
||||
|
||||
- Windows and Scroll Bars
|
||||
|
||||
- Radial Progress Bar
|
||||
|
||||
- Sprite
|
||||
|
||||
### ANSI C Source Code
|
||||
|
||||
GUIX is written completely in ANSI C and is portable immediately to
|
||||
virtually any processor architecture that has an ANSI C compiler and
|
||||
ThreadX support. Although written in ANSI C, GUIX uses an object
|
||||
oriented model and inheritance.
|
||||
|
||||
### Not A Black Box
|
||||
|
||||
Most distributions of GUIX include the complete C source code. This
|
||||
eliminates the "black-box" problems that occur with many commercial GUI
|
||||
implementations. By using GUIX, applications developers can see exactly
|
||||
what the GUI is doing—there are no mysteries!
|
||||
|
||||
Having the source code also allows for application specific
|
||||
modifications. Although not recommended, it is certainly beneficial to
|
||||
have the ability to modify the GUI if it is required. These features are
|
||||
especially comforting to developers accustomed to working with in-house
|
||||
or public domain products. They expect to have source code and the
|
||||
ability to modify it. GUIX is the ultimate GUI software for such
|
||||
developers.
|
||||
|
||||
## Embedded GUI Applications
|
||||
|
||||
Embedded GUI applications are applications that have a user interface
|
||||
requirement and execute on microprocessors hidden inside products such
|
||||
as cellular phones, communication equipment, automotive engines, laser
|
||||
printers, medical devices, and so forth. Such applications almost always
|
||||
have some memory and performance constraints. Another distinction of
|
||||
embedded GUI is that their software and hardware have a dedicated
|
||||
purpose.
|
||||
|
||||
### Real-time GUI Software
|
||||
|
||||
Basically, GUI software that must perform its processing within an exact
|
||||
period of time is called *real-time GUI* software, and when time
|
||||
constraints are imposed on GUI applications, they are classified as
|
||||
realtime applications. Embedded GUI applications are almost always
|
||||
real-time because of their inherent interaction with the external world.
|
||||
|
||||
## GUIX Benefits
|
||||
|
||||
The primary benefits of using GUIX for embedded applications are
|
||||
high-performance, feature rich, and very small memory requirements. GUIX
|
||||
is also completely integrated with the high-performance, multitasking
|
||||
ThreadX real-time operating system.
|
||||
|
||||
### Improved Responsiveness
|
||||
|
||||
The high-performance GUIX product enables applications to respond faster
|
||||
than ever before. This is especially important for embedded applications
|
||||
that either have a significant volume of visual information or strict
|
||||
timing requirements on displaying such information.
|
||||
|
||||
### Software Maintenance
|
||||
|
||||
Using GUIX allows developers to easily partition the GUI aspects of
|
||||
their embedded application. This partitioning makes the entire
|
||||
development process easy and significantly enhances future software
|
||||
maintenance.
|
||||
|
||||
### Increased Throughput
|
||||
|
||||
GUIX provides the highest-performance GUI available, which directly
|
||||
transfers to the embedded application. GUIX applications are able to
|
||||
process user interface information faster than non-GUIX applications!
|
||||
|
||||
### Processor Isolation
|
||||
|
||||
GUIX provides a robust, processor-independent interface between the
|
||||
application and the underlying processor and display hardware. This
|
||||
allows developers to concentrate on the high-level aspects of the user
|
||||
interface rather than spending extra time dealing with display hardware
|
||||
issues.
|
||||
|
||||
### Ease of Use
|
||||
|
||||
GUIX is designed with the application developer in mind. The GUIX
|
||||
architecture and service call interface are easy to understand. As a
|
||||
result, GUIX developers can quickly use its advanced features.
|
||||
|
||||
### Improve Time to Market
|
||||
|
||||
The powerful features of GUIX accelerate the software development
|
||||
process. GUIX abstracts most processor and display hardware issues,
|
||||
thereby removing these concerns from a majority of application user
|
||||
interface implementation. This feature, coupled with the ease-of-use and
|
||||
advanced feature set, results in a faster time to market!
|
||||
|
||||
### Protecting the Software Investment
|
||||
|
||||
GUIX is written exclusively in ANSI C and is fully integrated with the
|
||||
ThreadX real-time operating system. This means GUIX applications are
|
||||
instantly portable to all ThreadX supported processors. Better yet, a
|
||||
completely new processor architecture can be supported with ThreadX in a
|
||||
matter of weeks. As a result, using GUIX ensures the application's
|
||||
migration path and protects the original development investment.
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: Chapter 2 - Installation and Use of GUIX
|
||||
description: This chapter contains a description of various issues related to installation, setup, and use of the high performance user interface product GUIX.
|
||||
---
|
||||
|
||||
# Chapter 2 - Installation and Use of GUIX
|
||||
|
||||
This chapter contains a description of various issues related to
|
||||
installation, setup, and use of the high performance user interface
|
||||
product GUIX.
|
||||
|
||||
## Host Considerations
|
||||
|
||||
Embedded development is usually performed on Windows or Linux (Unix)
|
||||
host computers. After the application is compiled, linked, and the
|
||||
executable is generated on the host, it is downloaded to the target
|
||||
hardware for execution.
|
||||
|
||||
Usually the target download is done from within the development tool's
|
||||
debugger. After download, the debugger is responsible for providing
|
||||
target execution control (go, halt, breakpoint, etc.) as well as access
|
||||
to memory and processor registers.
|
||||
|
||||
Most development tool debuggers communicate with the target hardware via
|
||||
on-chip debug (OCD) connections such as JTAG (IEEE 1149.1) and
|
||||
Background Debug Mode (BDM). Debuggers also communicate with target
|
||||
hardware through In-Circuit Emulation (ICE) connections. Both OCD and
|
||||
ICE connections provide robust solutions with minimal intrusion on the
|
||||
target resident software.
|
||||
|
||||
As for resources used on the host, the source code for GUXI is delivered
|
||||
in ASCII format and requires approximately 30 Mbytes of space on the
|
||||
host computer's hard disk.
|
||||
|
||||
## Target Considerations
|
||||
|
||||
GUIX requires between 5 KBytes and 80 Kbytes of Read-Only Memory (ROM)
|
||||
on the target. Another 5 to 10KBytes of the target's Random Access Memory (RAM) are required for the GUIX thread stack and other global data structures.
|
||||
|
||||
In addition, GUIX requires the use of a ThreadX timer and a ThreadX
|
||||
mutex object. These facilities are used for periodic processing needs
|
||||
and thread protection inside GUIX.
|
||||
|
||||
## Product Distribution
|
||||
|
||||
GUIX can be obtained from our public source code repository at <https://github.com/azure-rtos/guix/>.
|
||||
|
||||
The following is a list of the important files common to most product distributions:
|
||||
|
||||
| Filename | Description |
|
||||
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| gx_api.h | This C header file contains all system equates, data structures, and service prototypes. |
|
||||
| gx_port.h | This C header file contains all target-specific and development tool-specific data definitions and structures. |
|
||||
| gx.a (or gx.lib) | This is the binary version of the GUIX C library. This is normally built by compiling and archiving the provided GUIX library source files, however this library may be provided in pre-built form depending on your hardware target and license type. |
|
||||
|
||||
> **Important:** *All files are in lower-case, making it easy to convert the commands to Linux (Unix) development platforms.*
|
||||
|
||||
## GUIX Installation
|
||||
|
||||
GUIX is installed by cloning the GitHub repository to your local machine. The following is typical syntax for creating a clone of the GUIX repository on your PC:
|
||||
|
||||
```c
|
||||
git clone https://github.com/azure-rtos/guix
|
||||
```
|
||||
|
||||
Alternatively you can download a copy of the repository using the download button on the GitHub main page.
|
||||
|
||||
You will also find instructions for building the GUIX library on the front page of the online repository.
|
||||
|
||||
**Note:** *Application software needs access to the GUIX library file, usually called **gx.a** (or **gx.lib**), and the C include files **gx_api.h** and **gx_port.h**. This is accomplished either by setting the appropriate path for the development tools or by copying these files into the application development area.*
|
||||
|
||||
## Using GUIX
|
||||
|
||||
Using GUIX is easy. Basically, the application code must include ***gx_api.h*** during compilation and link with the GUIX library ***gx.a*** (or ***gx.lib**)*.
|
||||
|
||||
There are four easy steps required to build a GUIX
|
||||
application:
|
||||
|
||||
| Steps | Description |
|
||||
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Step 1: | Include the ***gx_api.h*** file in all application files that use GUIX services or data structures. |
|
||||
| Step 2: | Initialize the GUIX system by calling ***gx_system_initialize*** from the ***tx_application_define*** function or an application thread. |
|
||||
| Step 3: | Create a display instance, create a canvas for the display, and create the root window and any other windows or widgets necessary. |
|
||||
| Step 4: | Compile application source and link with the GUIX runtime library ***gx.a*** (or ***gx.lib***). The resulting image can be downloaded to the target and executed! |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Each GUIX port is delivered with a demonstration application that
|
||||
executes on specific display hardware. The same basic demonstration is
|
||||
delivered with all versions of GUIX. It is always a good idea to get the
|
||||
demonstration system running first.
|
||||
|
||||
If the demonstration system does not run properly, perform the following
|
||||
operations to narrow the problem:
|
||||
|
||||
1. Determine how much of the demonstration is running.
|
||||
|
||||
2. Increase the stack size of the GUIX thread by changing the
|
||||
compile-time constant **GX_THREAD_STACK_SIZE** and recompiling
|
||||
the GUIX library
|
||||
|
||||
3. Recompile the GUIX library with the appropriate debug options listed
|
||||
in the configuration option section.
|
||||
|
||||
4. Examine the return status from all API calls.
|
||||
|
||||
5. Determine if there is an internal system error by setting a
|
||||
breakpoint at the function ***_gx_system_error_process***. There
|
||||
error code and caller should give clues as to what might be going
|
||||
wrong.
|
||||
|
||||
6. Temporarily bypass any recent changes to see if the problem
|
||||
disappears or changes.
|
||||
|
||||
## Configuration Options
|
||||
|
||||
There are several configuration options when building the GUIX library and the application using GUIX. These options are used to tune the library size and feature set to best fit your application requirements. For example, if your application will have only one thread utilizing the GUIX API services, the configuration flag **GX_DISABLE_MULTITHREAD_SUPPORT** should be defined to eliminate the overhead associated with protecting critical code sections from pre-emption by multiple threads. The various configuration flags can be defined in the application source, on the command line, or within the ***gx_user.h*** include file.
|
||||
|
||||
Whenever the GUIX library configuration flags are modified, it is
|
||||
required to rebuild both the GUIX library and your application modules
|
||||
for the configuration changes to take effect.
|
||||
|
||||
The complete list of configuration flags is documented in Appendix H:
|
||||
GUIX Build-Time Configuration Flags.
|
||||
|
||||
## GUIX Version ID
|
||||
|
||||
The current version of GUIX is available to both the user and the
|
||||
application software during runtime. The programmer can obtain the GUIX version from examination of the ***gx_port.h*** file. In addition, this file also contains a version history of the corresponding port Application software can obtain the GUIX version by examining the global string ***_gx_version_id*** in ***gx_port.h***.
|
||||
|
||||
Application software can also obtain release information from the
|
||||
constants shown below defined in ***gx_api.h**.* These constants
|
||||
identify the current product release by name and the product major and
|
||||
minor version.
|
||||
|
||||
```C
|
||||
#define __PRODUCT_GUIX__
|
||||
|
||||
#define __GUIX_MAJOR_VERSION__
|
||||
|
||||
#define __GUIX_MINOR_VERSION__
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: Chapter 5 - GUIX Display Drivers
|
||||
description: GUIX Display drivers define the software interface between the abstract drawing canvas and the physical display hardware.
|
||||
---
|
||||
# Chapter 5 - GUIX Display Drivers
|
||||
|
||||
GUIX Display drivers define the software interface between the abstract drawing canvas and the physical display hardware. The GUIX display driver implements the lowest-level drawing functions that actually change pixel color information in the canvas memory and transfer the canvas memory to the physical display frame buffer in double-buffered systems.
|
||||
|
||||
GUIX Display drivers are defined by a structure containing the physical display parameters and a set of function pointers to the low-level driver functions. By using these indirect function pointers, the abstract canvas and widget drawing functions are made completely independent of the hardware details.
|
||||
|
||||
GUIX provides a complete, fully functional, default set of drawing functions for each supported color depth and color format. When implementing a display driver with no specific hardware acceleration capability or other hardware specific considerations, these default drawing functions are normally sufficient for the final driver implementation. For these simplest of drivers, the only function that normally needs to be implemented in the driver software is a function to configure the hardware device. This often involves initializing various hardware registers to define the LCD display clock, display dimensions etc. For all other functions, the driver implementation simply initialize the GX_DISPLAY function pointers to the default function implementations for the desired color depth and format.
|
||||
|
||||
When implementing a custom display driver, the best practice is to first initialize your display driver drawing function pointers with the default software implementation for the color depth you want to support, then replace those function pointers where desired to call your custom function implementations (if any). To assist with this, there is a default setup function available for each supported color depth and format. For example, if you are writing a 16 bit 5:6:5 format RGB display driver, the first thing your custom driver would normally do is invoke the generic setup routine for this color depth:
|
||||
|
||||
UINT my_custom_565_display_driver(GX_DISPLAY *display)
|
||||
|
||||
```c
|
||||
{
|
||||
/* Perform standard function pointer setup. */
|
||||
_gx_display_driver_565rgb_setup(display, GX_NULL, my_buffertoggle);
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
The parameter my_buffer_toggle above is a pointer to your display driver buffer toggle function (which may be GX_NULL if your driver is single-buffered and drawing directly to the hardware frame buffer).
|
||||
|
||||
If you are writing a custom display driver, you will need to include the gx_display.h header file in your custom driver source, which is an internal use header file not available to application level software.
|
||||
|
||||
The GUIX display level drawing functions receive as input a pointer to a **GX_DRAW_CONTEXT** structure. The **GX_DRAW_CONTEXT** structure defines the clipping coordinates for the current drawing operation along with the brush and colors being used. Each drawing function receives as input additional parameters specific to the function requirements.
|
||||
|
||||
The signature of the **GX_DISPLAY** driver entry point is defined as
|
||||
|
||||
```c
|
||||
UINT <device>_graphics_driver_<format>(GX_DISPLAY *display)
|
||||
```
|
||||
|
||||
While the name of this function is completely up to the implementor, the convention for the drivers provided with GUIX is to use a hardware specific device name in the \<device\> field and color format for \<format\> field above.
|
||||
|
||||
This function must initialize the **GX_DISPLAY** structure provided as input and perform any hardware setup that is required. The **GX_DISPLAY** structure contains the following fields.
|
||||
|
||||
| Field | Description |
|
||||
| --- | --- |
|
||||
| ULONG gx_display_id | This is a field for use by the application, in cases where more than one instance of a particular driver is created. |
|
||||
| CHAR *gx_display_name | An optional name used to identify the driver. |
|
||||
| GX_DISPLAY *gx_display_created_next | This field is initialized by GUIX, and is used to create and maintain a list of all GX_DISPLAY instances. |
|
||||
| GX_DISPLAY *gx_display_created_previous | This field is initialized by GUIX, and is used to create and maintain a list of all GX_DISPLAY instances. |
|
||||
| GX_VALUE gx_display_color_format | This field should reflect the graphics data format supported by this driver. The color format types are defined in the gx_api.h header file. |
|
||||
| GX_VALUE gx_display_width | This field should be initialized to hold the physical display width, in pixels. |
|
||||
| GX_VALUE gx_display_height | This field should be initialized to hold the physical display height, in pixels. |
|
||||
| GX_COLOR *gx_display_color_table | This is a pointer to a table used to convert color ID values to color format specific color values. |
|
||||
| GX_PIXELMAP *gx_display_pixelmap_table | This is a pointer to the active pixelmap table for this display. |
|
||||
| GX_FONT *gx_display_font_table | This is a pointer to the active font table for this display. |
|
||||
| GX_COLOR *gx_display_palette | For palette mode drivers, this is a pointer to the active color palette. For drivers that do not use a color palette, this pointer is GX_NULL. |
|
||||
| UINT gx_display_pixelmap_table_size | Number of entries in the active pixelmap table. |
|
||||
| UINT gx_display_font_table_size | Number of entries in the active font table. |
|
||||
| UINT gx_display_palette_size | Number of entries in color palette (if any). |
|
||||
| ULONG gx_display_handle | A unique identifier, or *handle*, that specifies the display.
|
||||
| UINT gx_display_driver_ready | This field is use to signal to GUIX when the driver is ready for operation. In some cases, the driver may require several levels of initialization and configuration, during which time GUIX must not attempt to utilize the driver. This flag should be set to 1 when the driver is ready to service drawing requests. |
|
||||
| VOID *gx_display_driver_data | This field is for use by the driver implementation. If the driver needs to create and reference additional information not available in the GX_DISPLAY structure, the driver should allocate space for and point to this additional data using this structure field. An example of driver-specific extra data might include the DMA channel being used by the driver or the SPI channel to which the display frame buffer is connected. |
|
||||
| VOID (*gx_display_driver_drawing_initiate)(struct GX_DISPLAY_STRUCT *display, struct GX_CANVAS_STRUCT *canvas) | This is a function pointer that, if not NULL, is invoked by the gx_canvas_drawing_initiate function. For display drivers that utilize a graphics accelerator or hardware graphics display list, this function might be used to begin a new display list. This function pointer can be NULL. |
|
||||
| VOID (*gx_display_driver_palette_set)(struct GX_DISPLAY_STRUCT *display, GX_COLOR *palette, INT count) | This is a pointer to a function to install a color palette. This function is NULL unless the driver operates in palette (also called color lookup table or CLUT) mode. |
|
||||
| VOID (*gx_display_driver_simple_line_draw)(GX_DRAW_CONTEXT *context, INT x1, INTy1, INT x2, INT y2) | This is a pointer to a function to implement generic line drawing, no anti-aliasing. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_simple_wide_line_draw)(GX_DRAW_CONTEXT *context, INT x1, INTy1, INT x2, INT y2) | This is a pointer to a function to implement generic wide line drawing, no anti-aliasing. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_anti_aliased_line_draw)(GX_DRAW_CONTEXT *context, INT x1, INTy1, INT x2, INT y2) | This is a pointer to a function to implement generic anti-aliased line drawing. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_anti_aliased_wide_line_draw)(GX_DRAW_CONTEXT *context, INT x1, INTy1, INT x2, INT y2) | This is a pointer to a function to implement generic anti-aliased wide line drawing. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_horizontal_line_draw)(GX_DRAW_CONTEXT *context, INT x1, INT x2, INT y) | This is a pointer to a function to implement the special case of horizontal line drawing. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_horizontal_pixelmap_line_draw)(GX_DRAW_CONTEXT *context, INT x1, INT x2, INT y, GX_PIXELMAP *map) | This is a pointer to a function to implement drawing a single pixelmap row. This function is used internally for pattern filling shapes. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_vertical_line_draw)(GX_DRAW_CONTEXT *context, INT y1, INT y2, INT x) | This is a pointer to a function to implement the special case of vertical line drawing. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_horizontal_pattern_line_draw)(GX_DRAW_CONTEXT *context, INT x1, INT x2, INT y) | This is a pointer to a function to implement horizontal pattern line drawing. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_vertical_pattern_line_draw)(GX_DRAW_CONTEXT *context, INT y1, INT y2, INT x) | This is a pointer to a function to implement vertical pattern line drawing. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_canvas_copy)(struct GX_CANVAS_STRUCT *source, struct GX_CANVAS_STRUCT *dest) | This is a pointer to a function to copy canvas data from one canvas to another. The source canvas invalid rectangle is used to define the copy area. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_canvas_blend)(struct GX_CANVAS_STRUCT *source, struct GX_CANVAS_STRUCT *dest) | This is a pointer to a function to alpha-blend canvas data from the source canvas with the existing data in the destination canvas. The source canvas invalid rectangle is used to define the blend area. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_pixelmap_blend)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp, GX_UBYTE alpha) | This is a pointer to a function to blend a pixelmap on the background canvas defined by the draw context. The supplied alpha value may be in addition to an alpha channel contained in the pixelmap data. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_pixelmap_draw)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp) | This is a pointer to a function to draw a pixelmap into the canvas defined by the draw context. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_jpeg_draw)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp) | This is a pointer to a function to decode a jpg image and render it directly to the canvas. This function is only provided if GX_SOFTWARE_DECODER_SUPPORT is defined. This function pointer can be NULL. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_png_draw)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp) | This is a pointer to a function to decode a png image and render it directly to the canvas. This function is only provided if GX_SOFTWARE_DECODER_SUPPORT is defined. This function pointer can be NULL. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_pixelmap_rotate)(GX_DRAW_CONTEXT *context, INT xpos, INT ypos, GX_PIXELMAP *pmp INT angle, INT rot_cx, INT rot_cy) | This is a pointer to a function to rotate a pixelmap and render the result directly to the canvas. This function is invoked by the gx_canvas_pixelmap_rotate API Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID *gx_display_driver_pixel_write)(GX_DRAW_CONTEXT *context, INT x, INT y, GX_COLOR color) | This is a pointer to a function to write one pixel into the canvas memory. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID *gx_display_driver_block_move)(GX_DRAW_CONTEXT *context, GX_RECTANGLE *block, INT xshift, INT yshift) | This is a pointer to a function to move or shift a block of pixels within a canvas. This function is primarily used for rapidly scrolling a window contents. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_pixel_blend)(GX_DRAW_CONTEXT *context, INT x, INT y, GX_COLOR color, GX_UBYTE alpha) | This function is used to alpha-blend the incoming pixel color value with the existing color value in the canvas memory at position x,y. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| GX_COLOR (*gx_display_driver_native_color_get)(GX_COLOR rawcolor) | This function converts a color from the 32-bit A:R:G:B color format used internally by GUIX to the native color format of the canvas and display. Some loss of color information is expected for display drivers running at lower color depths. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| USHORT (*gx_display_driver_row_pitch_get)(USHORT width) | Returns the byte count or stride of one row of graphics data given the requested canvas width. This function is used to calculate the size of the memory area needed to create a canvas. The row pitch and width are not always the same due to hardware scan line alignment constraints. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_buffer_toggle)(struct GX_CANVAS_STRUCT *canvas, GX_RECTANGLE *dirty_area) | This is a pointer to a function to toggle between the working and visible frame buffers for double-buffered memory systems. This function must first instruct the hardware to begin using the new frame buffer, then copy the modified portion of the new visible buffer to the companion buffer, to insure the two buffers stay in synch. |
|
||||
| VOID (*gx_display_driver_polygon_draw)(GX_DRAW_CONTEXT *context, INT num_points, GX_POINT *vertices | Pointer to a function to draw a polygon. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_polygon_fill)(GX_DRAW_CONTEXT *context, INT num_points, GX_POINT *vertices | Pointer to a function to draw a filled polygon. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_circle_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | Pointer to a function to draw a circle. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_anti_aliased_circle_draw) (GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | Pointer to a function to draw an anti-aliased circle. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_wide_circle_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | Pointer to a function to draw a circle with a wide outline. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_wide_anti_aliased_circle_draw) (GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | Pointer to a function to draw an anti-aliased circle with a wide outline. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_circle_fill)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r) | Pointer to a function to draw a filled circle. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_arc_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INT end_angle) | Pointer to a function to draw an arc. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_anti_aliased_arc_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INTend_angle) | Pointer to a function to draw an anti-aliased arc. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_wide_arc_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INT end_angle) | Pointer to a function to draw an arc with a wide outline. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_anti_aliased_wide_arc_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INTend_angle) | Pointer to a function to draw an anti-aliased arc. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_arc_fill)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INT end_angle) | Pointer to a function to draw a filled arc. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_pie_fill)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, UINT r, INT start_angle, INT end_angle) | Pointer to a function to draw a filled pie. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_ellipse_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | Pointer to a function to draw an ellipse. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_anti_aliased_ellipse_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | Pointer to a function to draw an ellipse. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_wide_ellipse_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | Pointer to a function to draw an ellipse with a wide outline. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_anti_aliased_wide_ellipse_draw)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | Pointer to a function to draw an ellipse with a wide outline. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_ellipse_fill)(GX_DRAW_CONTEXT *context, INT xcenter, INT ycenter, INT a, INT b) | Pointer to a function to draw a filled ellipse. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_8bit_glyph_draw)(GX_DRAW_CONTEXT *context, GX_RECTANGLE *draw_area, GX_POINT *map_offset, constGX_GLYPH *glyph) | Pointer to function to draw one 8-bit aliased text glyph to the canvas using the brush of the current drawing context. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_4bit_glyph_draw)(GX_DRAW_CONTEXT *context, GX_RECTANGLE *draw_area, GX_POINT *map_offset, const GX_GLYPH *glyph) | Pointer to function to draw one 4-bit aliased text glyph to the canvas using the brush of the current drawing context. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
| VOID (*gx_display_driver_1bit_glyph_draw)(GX_DRAW_CONTEXT *context, GX_RECTANGLE *draw_area, GX_POINT *map_offset, const GX_GLYPH *glyph) | Pointer to function to draw one 1-bit monochrome text glyph to the canvas using the brush of the current drawing context. Default implementations of this function are provided for each supported color depth and color format. |
|
||||
|
||||
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: GUIX Example
|
||||
description: The GUIX demonstration system is delivered with a small example, defined in examples/helloworld/helloworld.c.
|
||||
---
|
||||
# GUIX Example
|
||||
|
||||
The GUIX demonstration system is delivered with a small example, defined in examples/helloworld/helloworld.c. This example illustrates the steps needed to take to initialize the GUIX system, to set up display drivers. The source code is listed on the following pages.
|
||||
|
||||
```c
|
||||
/* This is a small demonstration of the high-performance GUIX embedded UI run-time environment. This demonstration consists of a simple "Hello World" prompt on top of the root window. */
|
||||
|
||||
/* Include necessary system files.
|
||||
|
||||
#include "tx_api.h"
|
||||
#include "gx_api.h"
|
||||
|
||||
/* Define constants for the GUIX Win32 demo. */
|
||||
|
||||
/* Define the display dimensions specific to this implementation. */
|
||||
#define DEMO_DISPLAY_WIDTH 320
|
||||
#define DEMO_DISPLAY_HEIGHT 240
|
||||
|
||||
/* Define the number of pixels on the canvas */
|
||||
#define DEFAULT_CANVAS_PIXELS (DEMO_DISPLAY_WIDTH * DEMO_DISPLAY_HEIGHT)
|
||||
|
||||
/* Define the ThreadX demo thread control block. */
|
||||
TX_THREAD demo_thread;
|
||||
|
||||
/* Define the stack for the demo thread. */
|
||||
ULONG demo_thread_stack[4096 / sizeof(ULONG)];
|
||||
|
||||
/* Define the GUIX resources for this demo. */
|
||||
|
||||
/* GUIX display represents the physical display device */
|
||||
GX_DISPLAY demo_display;
|
||||
|
||||
/* GUIX canvas is the frame buffer on top of GUIX displays. */
|
||||
GX_CANVAS default_canvas;
|
||||
|
||||
/* The root window is a special GUIX background window, right on top of the canvas. */
|
||||
GX_WINDOW_ROOT demo_root_window;
|
||||
|
||||
/* GUIX Prompt displays a string. */
|
||||
GX_PROMPT demo_prompt;
|
||||
|
||||
/* Memory for the frame buffer. */
|
||||
GX_COLOR default_canvas_memory[DEFAULT_CANVAS_PIXELS];
|
||||
|
||||
/* Define GUIX strings ID for the demo. */
|
||||
enum demo_string_ids
|
||||
{
|
||||
SID_HELLO_WORLD = 1,
|
||||
SID_MAX
|
||||
};
|
||||
|
||||
/* Define GUIX string for the demo. */
|
||||
CHAR *demo_strings[] = {
|
||||
NULL,
|
||||
"Hello World"
|
||||
};
|
||||
|
||||
/* User-defined color ID */
|
||||
#define GX_COLOR_ID_BLACK GX_FIRST_USER_COLOR
|
||||
#define GX_COLOR_ID_WHITE (GX_FIRST_USER_COLOR + 1)
|
||||
|
||||
/* User-defined color table. */
|
||||
static GX_COLOR demo_color_table[] =
|
||||
{
|
||||
/* First, bring in GUIX default color table. These colors are used by GUIX internals. */
|
||||
GX_SYSTEM_DEFAULT_COLORS_DECLARE,
|
||||
|
||||
/* In this demo, two color entries are added to the color table. */
|
||||
GX_COLOR_BLACK,
|
||||
GX_COLOR_WHITE
|
||||
};
|
||||
|
||||
/* Define prototypes. */
|
||||
|
||||
VOID demo_thread_entry(ULONG thread_input);
|
||||
|
||||
int main(void)
|
||||
{
|
||||
/* Enter ThreadX. */
|
||||
tx_kernel_enter();
|
||||
|
||||
return (0);
|
||||
}
|
||||
|
||||
VOID tx_application_define(void *first_unused_memory)
|
||||
{
|
||||
/* Create the main demo thread. */
|
||||
tx_thread_create(&demo_thread, "GUIX Demo Thread", demo_thread_entry, 0,
|
||||
demo_thread_stack, sizeof(demo_thread_stack),
|
||||
1, 1, TX_NO_TIME_SLICE, TX_AUTO_START);
|
||||
}
|
||||
|
||||
VOID demo_thread_entry(ULONG thread_input)
|
||||
{
|
||||
|
||||
GX_RECTANGLE root_window_size;
|
||||
GX_RECTANGLE prompt_position;
|
||||
|
||||
/* Initialize GUIX. */
|
||||
gx_system_initialize();
|
||||
|
||||
/* Install the demo string table. */
|
||||
gx_system_string_table_set(demo_strings, SID_MAX);
|
||||
|
||||
/* Install the demo color table. */
|
||||
gx_system_color_table_set(demo_color_table, sizeof(demo_color_table) /
|
||||
sizeof(GX_COLOR));
|
||||
|
||||
/* Create the demo display and associated driver. */
|
||||
gx_display_create(&demo_display, "demo display",
|
||||
win32_graphics_driver_setup_16bpp,
|
||||
DEMO_DISPLAY_WIDTH, DEMO_DISPLAY_HEIGHT);
|
||||
|
||||
/* Create the default canvas. */
|
||||
gx_canvas_create(&default_canvas, "demo canvas",&demo_display,
|
||||
GX_CANVAS_MANAGED | GX_CANVAS_VISIBLE,
|
||||
DEMO_DISPLAY_WIDTH,DEMO_DISPLAY_HEIGHT,
|
||||
default_canvas_memory, sizeof(default_canvas_memory));
|
||||
|
||||
/*Define the size of the root window. */
|
||||
gx_utility_rectangle_define(&root_window_size, 0, 0,
|
||||
DEMO_DISPLAY_WIDTH - 1, DEMO_DISPLAY_HEIGHT - 1);
|
||||
|
||||
/* Create a background root window and attach to the canvas. */
|
||||
gx_window_root_create(&demo_root_window, "demo root window", &default_canvas,
|
||||
GX_STYLE_BORDER_NONE, GX_ID_NONE, &root_window_size);
|
||||
|
||||
/* Set the root window to be black. */
|
||||
gx_widget_background_set(&demo_root_window, GX_COLOR_ID_BLACK,
|
||||
GX_COLOR_ID_BLACK);
|
||||
|
||||
/* Create a text prompt on the root window. Set the text color to white, and the background to black. */
|
||||
|
||||
/* Define the size and the position of the prompt. */
|
||||
gx_utility_rectangle_define(&prompt_position, 100, 90, 220, 130);
|
||||
|
||||
/* Create the prompt on top of the root window using the string defined by string ID SID_HELLO_WORLD. */
|
||||
gx_prompt_create(&demo_prompt, NULL, &demo_root_window, SID_HELLO_WORLD,
|
||||
GX_STYLE_NONE, GX_ID_NONE, &prompt_position);
|
||||
|
||||
/* Set the text color to be white, and the background color to be black. */
|
||||
gx_prompt_text_color_set(&demo_prompt, GX_COLOR_ID_WHITE, GX_COLOR_ID_WHITE);
|
||||
gx_widget_background_set(&demo_prompt, GX_COLOR_ID_BLACK,GX_COLOR_ID_BLACK);
|
||||
|
||||
/* Show the root window. */
|
||||
gx_widget_show(&demo_root_window);
|
||||
|
||||
/* let GUIX run! */
|
||||
gx_system_start();
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: GUIX Studio User Guide
|
||||
description: This guide provides comprehensive information about GUIX Studio, the Microsoft Windows-based rapid UI development environment specifically designed for the GUIX runtime library from Eclipse Foundation.
|
||||
---
|
||||
# Chapter 1: Introduction to GUIX Studio
|
||||
|
||||
GUIX Studio is a Microsoft Windows-based rapid UI development environment specifically designed for the GUIX runtime library from Eclipse Foundation.
|
||||
|
||||
Embedded UI Developers can utilize the GUIX Studio WYSIWYG screen designer to quickly create and update their embedded UI using the GUIX run-time environment. GUIX Studio designs are saved and maintained in a GUIX Studio project file, which has the extension .gxp. When your design is ready for execution on the target, GUIX Studio generates C code that contains all the necessary UI information and code.
|
||||
|
||||
## GUIX Studio Requirements
|
||||
|
||||
In order to function properly, GUIX Studio requires *Windows XP* (or above). The system should have a minimum of 200MB of RAM, 2GB of available hard-disk space, and a minimum display of 1024x768 with 256 colors. In addition, the embedded application must be running on *ThreadX/GUIX V6.0* or later.
|
||||
|
||||
If you would like to be able to build and run the embedded UI application as a stand-alone Windows executable, you will also need a compiler or build environment capable of compiling C source code to produce a Windows executable. The evaluation package included with GUIX Studio also includes Visual Studio 2019 compatible project files and solutions for each of the provided example applications. If you are using a different compiler, you will need to create your own project files or make files for the purposes of building your example applications.
|
||||
|
||||
## GUIX Studio Constraints
|
||||
|
||||
The GUIX Studio UI design tool has several constraints, as follows:
|
||||
|
||||
- A maximum of 4 displays per project.
|
||||
- A maximum of 100,000 widgets per GUIX Studio project.
|
||||
- A maximum of 100,000 distinct resources, e.g., colors, fonts, pixelmaps, strings, etc.
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Installation and Use of GUIX Studio
|
||||
description: This chapter contains a description of various issues related to installation, setup, and usage of the GUIX Studio UI system design tool.
|
||||
---
|
||||
# Chapter 2: Installation and Use of GUIX Studio
|
||||
|
||||
This chapter contains a description of various issues related to installation, setup, and usage of the GUIX Studio UI system design tool.
|
||||
|
||||
## Product Distribution
|
||||
|
||||
You can obtain the GUIX Studio app from the [Microsoft App Store](https://microsoft.com/store/apps) by searching for GUIX Studio, or by going directly to [the GUIX Studio page](https://www.microsoft.com/p/azure-rtos-guix-studio/9pbm1k1r7q0f?activetab=pivot:overviewtab). Then do the following.
|
||||
|
||||
1. From the GUIX Studio page in the App Store, click the **Get** or **Install** button to download GUIX Studio.
|
||||
|
||||
1. Your browser may display a message asking if you want to open the App Store. If it does, choose the **Open** button.
|
||||
|
||||
1. When the install finishes, choose the **Launch** button.
|
||||
|
||||
1. The first time that GUIX Studio launches, it displays a dialog box asking if you want to clone the GUIX repo to your local computer. You can either choose to clone the repository, point to where you have already cloned the repo, or choose not to clone the repo at all (in which case, one example project is installed on your computer).
|
||||
|
||||
|
||||
|
||||
> **Note:** You can return to this dialog box at any time by choosing **Configure** from the main menu of GUIX Studio, followed by **GUIX Repository**.
|
||||
|
||||
After the startup process is finished, you will be ready to use GUIX Studio.
|
||||
|
||||
## Using GUIX Studio
|
||||
|
||||
Using GUIX Studio is easy - simply run GUIX Studio via the "***Start***" button. At this point you will observe the GUIX Studio UI. You are now ready to use GUIX Studio to graphically create your embedded UI. From here you create a new project or open an existing project, including the GUIX example projects.
|
||||
|
||||
> **Note:** You can also double-click on any GUIX Studio project file with an extension of "**gxp,**" which will automatically launch GUIX Studio and open the referenced project.
|
||||
|
||||
## GUIX Studio Project Samples
|
||||
|
||||
A series of example GUIX Studio project files with the extension "***gxp***" are found in the "***Samples***" sub-directory of your installation. These pre-built example projects will help you get comfortable with using GUIX Studio.
|
||||
|
||||
One example project file that is always present is the file ***samples/demo_guix_simple/guix_simple.gxp***. This example project file shows the definition of a simple GUIX UI, as described in ***Chapter 7*** of this document.
|
||||
|
||||
|
||||
|
||||
**Figure 1**
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
- **Ctrl + N:** New Project
|
||||
- **Ctrl + O:** Open Project
|
||||
- **Ctrl + S:** Save Project
|
||||
- **Ctrl + Shift + S:** Save Project As
|
||||
- **Alt + F4:** Exit
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
title: Description of GUIX Studio
|
||||
description: This chapter contains a description of the GUIX Studio system analysis tool.
|
||||
---
|
||||
# Chapter 3: Description of GUIX Studio
|
||||
|
||||
This chapter contains a description of the GUIX Studio system analysis tool. A description of the overall functionality of the GUI is found in this chapter.
|
||||
|
||||
## GUIX Studio Views
|
||||
|
||||
There are five principal areas of the GUIX Studio UI, namely the ***Toolbar***, ***Project View***, ***Properties View***, ***Target View***, and ***Resource View***. ***Figure 2*** shows the basic GUIX Studio UI. Each of the views is further discussed in the following sub-sections.
|
||||
|
||||
|
||||
|
||||
**Figure 2**
|
||||
|
||||
### Title
|
||||
|
||||
- GUIX Studio 18: The ***Title*** displays the GUIX Studio version as well as the currently open project, as shown at the top of ***Figure 2*** previously.
|
||||
|
||||
### Toolbar
|
||||
|
||||
The ***Toolbar*** shows the buttons available to the GUIX Studio developer, as shown in ***Figure 3***.
|
||||
|
||||
|
||||
|
||||
**Figure 3**
|
||||
|
||||
The toolbar buttons are defined as follows:
|
||||
|
||||
 Creates a new GUIX Studio project
|
||||
|
||||
 Opens an existing GUIX Studio project
|
||||
|
||||
 Saves the project
|
||||
|
||||
 Cut widget selected, including children
|
||||
|
||||
 Copy selected widget, including children
|
||||
|
||||
 Paste widget and children
|
||||
|
||||
 Left-align selected widgets
|
||||
|
||||
 Right-align selected widgets
|
||||
|
||||
 Top-align selected widgets
|
||||
|
||||
 Bottom-align selected widgets
|
||||
|
||||
 Equally space selected widgets vertically
|
||||
|
||||
 Equally space selected widgets horizontally
|
||||
|
||||
 Make selected widgets equal width
|
||||
|
||||
 Make selected widgets equal height
|
||||
|
||||
 Move selected widgets to front
|
||||
|
||||
 Move selected widgets to back
|
||||
|
||||
 Size selected widget to content Zoom out target screen
|
||||
|
||||
 Zoom out target screen
|
||||
|
||||
 Zoom in target screen
|
||||
|
||||
 Record Macro
|
||||
|
||||
 Playback Macro
|
||||
|
||||
 Run Application
|
||||
|
||||
 About GUIX Studio
|
||||
|
||||
### Project View
|
||||
|
||||
The ***Project View*** shows the hierarchical list GUIX objects that comprise the embedded UI. New GUIX objects can be added by clicking on the parent object and then selecting an object from the ***Insert*** menu (or by right-clicking on the object and selecting from the right-click menu). ***Figure 4*** below shows the GUIX Studio ***Project View***.
|
||||
|
||||
|
||||
|
||||
**Figure 4**
|
||||
|
||||
### Properties View
|
||||
|
||||
The ***Properties View*** shows detailed property information of the currently selected GUIX object, which can be selected via the ***Project View*** or by clicking directly on the object in the ***Target View***. ***Figure 5*** below shows the GUIX Studio ***Properties View***.
|
||||
|
||||
|
||||
|
||||
**Figure 5**
|
||||
|
||||
### Target View
|
||||
|
||||
The ***Target View*** is the WYSIWYG screen design and layout area. This view is meant to represent the physical display or displays available on your target hardware. Objects can be selected, moved, resized, etc. via simple mouse operations. In addition, alignment and Z-order button operations are available on selected objects in the Target View. Selecting an object in the ***Target View*** will also result in the properties for that object to be displayed in the ***Properties View***. ***Figure 6*** below shows the GUIX Studio ***Target View***.
|
||||
|
||||
|
||||
|
||||
**Figure 6**
|
||||
|
||||
### Resource View
|
||||
|
||||
The ***Resource View*** is used to manage the resources (colors, fonts, pixelmaps, and strings) available to applications screens defined for each display. You can click on the resource view group headers to expand each group and examine the group contents. ***Figure 7*** below shows the GUIX Studio ***Resource View***.
|
||||
|
||||
|
||||
|
||||
**Figure 7**
|
||||
|
||||
The title of the resource groups indicates current theme name. If multi themes available, you are able to switch between themes by clicking on the up and down arrow.
|
||||
|
||||
Each resource group in the view above can be expanded or collapsed by clicking on the group header. A more detailed description of each resource groups follows in the next chapter.
|
||||
|
||||
## The GUIX Studio Project
|
||||
|
||||
A GUIX Studio project maintains information about your UI screen design and UI resources. The project data is saved to an XML format file with the extension ".***gxp***". Since the project file is an XML schema file, it can be versioned controlled and shared similar to any other source file.
|
||||
|
||||
When you first start using GUIX Studio, you will need to either open one of the example projects provided with the distribution or create a new project. All of your work is saved to the project data file.
|
||||
|
||||
GUIX Studio also produces ANSI C source files. These source files contain either your application resources or data structures describing your designed screens. GUIX Studio also writes to these generated source files API functions that know to utilize the generated data structures to dynamically create your application screens. Your application software will simply invoke the provided API functions to create the screens you have designed within GUIX Studio.
|
||||
|
||||
As you progress in designing your user interface, you will periodically want to use GUIX Studio to generate the GUIX compatible output files that will allow you to build and run the interface you have designed. You can compile and run the generated source files for either your target hardware or on your Windows desktop that simulates ThreadX and GUIX.
|
||||
|
||||
## GUIX Studio Project Organization
|
||||
|
||||
It is helpful to have some knowledge of the basic organization of a GUIX Studio project to understand how to use GUIX Studio effectively and to understand the information presented in the Project View of the GUIX Studio IDE. The Project View is a summary visual representation of all of the information contained in your project.
|
||||
|
||||
Before describing the project, it is necessary to define few terms. First, we use the term **Display** to mean a physical display device. This is most often an LCD display device but it could be using other technology. The next term is **Screen**, which mean a top-level GUIX object, usually a GUIX Window, and all of its associated child elements. A Screen is a software construct that can be defined and modified at runtime. Finally, a **Theme** is a collection of resources. A theme includes a table of color definitions, font definitions, and pixelmap definitions that are designed to work well together and present your end user with a consistent look and feel.
|
||||
|
||||
The project first includes a set of global information such as the project name, number of displays supported, the resolution and color format of each display, the number of languages supported, the name of each supported language. The project name is the first node displayed in the Project View.
|
||||
|
||||
The project next organizes all of the information required for up to 4 physical displays and the screens and resources available to each display. The display names are the next level nodes in the Project View tree.
|
||||
|
||||
A unique feature of the GUIX Studio application is built-in support for multiple physical displays, each with its own x,y resolution, color format, screens, and resources. While the vast majority of GUIX applications utilize only one physical display, this capability is important for those making a product that must support multiple simultaneous physical displays.
|
||||
|
||||
Beneath each display definition are the top-level windows or screens defined for that display. The screen definitions can be nested to any level depending on the number and nesting of child widgets on each screen.
|
||||
|
||||
This screen and child widget organization is displayed in a graphical manner in the Project View.
|
||||
|
||||
Also associated with each display are the Themes supported by the display and the resource content composing each Theme. If your project includes multiple displays, you will notice that the Resource View changes its content when you select one display and then another. This is because the resource content is linked to each display. Not only the color format may be different, but the pixelmaps, colors, and fonts you choose to use may vary from one physical display to another.
|
||||
|
||||
The final component maintained by the project is the string table data associated with each display. Since displays can be of very different x,y resolutions, the string data is maintained independently for each display defined in the project.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,179 @@
|
||||
---
|
||||
title: GUIX Studio Screen Designer
|
||||
description: Designing application screens is the primary purpose of GUIX Studio.
|
||||
---
|
||||
# Chapter 5: GUIX Studio Screen Designer
|
||||
|
||||
Designing application screens is the primary purpose of GUIX Studio. Screen design is accomplished through all the various views described previously in Chapter 3. However, the main element of screen design in GUIX Studio is the ***Target View***, which is where all the screen elements are shown visually and in exactly the same manner they will appear on the embedded target display. These screen elements can be selected, moved, resized, etc. via simple mouse and button operations. In addition, alignment and Z-order button operations are available on selected object(s). The following sub-sections describe various features of GUIX Studio screen design.
|
||||
|
||||
## Creating/Configuring Projects
|
||||
|
||||
Creating projects in GUIX Studio is straightforward – select the ***New Project*** button or the menu selection ***Project, New Project***. Next, GUIX Studio presents the ***Configure Project*** dialog. From this dialog, basic display settings, as well as path information for where to locate code generated by GUIX Studio is specified.
|
||||
|
||||
When a new project is created, the configure project dialog is presented. This is where the developer specifies the number of hardware displays available on the target and the properties each display. Properties include the display's logical name, x/y resolution, color depth and format, and other display properties. GUIX Studio supports multiple displays in the same project. If additional displays are required, the ***Number of Displays*** field should be changed to match the number of displays on the embedded device. The maximum number of displays in a project is 4. ***Figure 21*** shows the Configure Project dialog.
|
||||
|
||||
Modifying the project and/or display settings is accomplished by either the menu option ***Configure, Project/Display*** or by selecting the project or display, right-clicking, and selecting ***Configure, Project/Display***. In either case, the ***Configure Project*** dialog is presented to facilitate changes to the project settings and/or display(s).
|
||||
|
||||
|
||||
|
||||
**Figure 21**
|
||||
|
||||
The Directories group is where you can specify the default output directories for the C source and header files produced by Studio. These directories are normally saved relative the project location to make it easy to move projects from one computer to another or from one filesystem to another.
|
||||
|
||||
The Additional Headers field is where you can specify custom header files. If more than one header file is needed, use semicolons to delimit the list.
|
||||
|
||||
When you invoke the Studio "Generate Application" or "Generate Resources" commands, these are the default directories into which those source files will be written. Of course, you can override these directory locations at any time by entering new locations in the Output Directory dialog.
|
||||
|
||||
## Selecting Widgets
|
||||
|
||||
Selecting widgets is done by either clicking on the widget in the ***Project View*** widget tree or by clicking on the widget visible in the ***Target View*** area. When a single widget is selected, its properties are displayed in the ***Property View*** area. ***Figure 22*** shows the widget "***button***" selected.
|
||||
|
||||
|
||||
|
||||
**Figure 22**
|
||||
|
||||
## Using Properties
|
||||
|
||||
As mentioned previously, the properties for a selected widget are presented in the ***Properties View***. All widgets have a common set of properties as well as some properties that are specific to the particular widget type. For example, a button widget has a ***Pushed*** property while a window widget does not. The following are the common set of widget properties:
|
||||
|
||||
| Property | Meaning |
|
||||
| ---------------- | ------------------------------------------------------------------------------------- |
|
||||
| Widget Type | Type of widget, for reference |
|
||||
| Widget Name | Name of widget, passed to the widget create function and used for variable naming in the generated source files. |
|
||||
| Widget ID | ID of widget. This ID value is used to generate signals from child widgets to their parent screens. |
|
||||
| Left | Left-most coordinate of widget |
|
||||
| Top | Top-most coordinate of widget |
|
||||
| Width | Width of widget in pixels |
|
||||
| Height | Height of widget in pixels |
|
||||
| Border | Type of widget border |
|
||||
| Transparent | Should be checked if the widget is partially transparent |
|
||||
| Draw Selected | Should be checked if the widget should initially draw itself in the selected state. |
|
||||
| Enable | Should be checked if the widget can be selected or clicked by the end user. |
|
||||
| Accepts Focus | Should be checked if the widget accepts focus. |
|
||||
| Runtime Allocate | Should be checked if the widget control block should be allocated dynamically. |
|
||||
| Normal Fill | Normal fill color resource id |
|
||||
| Selected Fill | Selected fill color resource id |
|
||||
| Draw Function | User-defined custom drawing function Name. If this field is blank, the standard drawing function for that widget type is used. |
|
||||
| Event Function | User-defined custom event handling function name. If blank, the standard event handling for this widget type is used. |
|
||||
|
||||
***Figure 23*** shows the properties of a simple window widget.
|
||||
|
||||
|
||||
|
||||
**Figure 23**
|
||||
|
||||
Many widget types have additional properties specific to each widget type.
|
||||
|
||||
For example, in Figure 23 above, the Window widget type supports a Wallpaper pixelmap Id, and a style setting indicating if the wallpaper should be centered or tiled.
|
||||
|
||||
Text widgets support a string ID field, along with text alignment styles and a font specification. The additional widget properties are normally intuitive once you have read the description of each widget type and the available styles and Create function parameters for that widget type.
|
||||
|
||||
## Manipulating Widgets
|
||||
|
||||
To manipulate a widget, is first must be selected. This is done by either clicking directly on the widget in the ***Target View*** or by selecting it in the ***Project View*** widget tree. Once selected, the widget will have a dashed outline. In this state, it may be moved by clicking on the widget and dragging it to the desired location on its parent. If the widget is a top-level widget, dragging the widget is effectively setting the widget's initial position on the target display. Of course, it is always possible to move or resize any widget at any time using the GUIX API.
|
||||
|
||||
To resize the widget's height, position the mouse on the top edge of the widget and wait for the mouse pointer to change to an up-down arrow. At this point, the widget height may be changed by moving the mouse while the right mouse button is depressed. The width of the mouse may be resized in a similar fashion by positioning the mouse pointer on the left edge of the widget. ***Figure 24*** shows the "***button***" widget resized and moved to the left/top area of the parent window.
|
||||
|
||||
|
||||
|
||||
**Figure 24**
|
||||
|
||||
## Manipulating Multiple Widgets
|
||||
|
||||
Selecting multiple widgets is accomplished by clicking on multiple widgets in the target view while holding the ***Ctrl*** key down. Doing this will show each of the widgets selected with a dashed-outline around it. Note that when selecting multiple widgets each widget in the selection group must a child of the same parent.
|
||||
|
||||
Once multiple widgets are selected, they may be simultaneously moved by clicking inside one on the selected widgets and moving the mouse with the right mouse button pushed down. In addition, the alignment buttons on the ***Tool Bar*** may be used to align the group of selected widgets. ***Figure 25*** shows both the "***button***" and "***new button***" widgets selected and ***Figure 26*** shows the result of the ***Align-Left*** button selection while these widgets are selected.
|
||||
|
||||
|
||||
|
||||
**Figure 25**
|
||||
|
||||
|
||||
|
||||
**Figure 26**
|
||||
|
||||
## Cut/Copy/Paste Operations
|
||||
|
||||
A selected widget in the ***Target View*** may be cut, copied, and pasted in standard fashion. Widgets and screens can be copied within one project, or copied from one project and pasted into another.The ***Tool Bar*** has buttons for cut, copy, and paste. There are also the same options in the Edit menu option. Note that when pasting a widget, the parent widget should be selected before pasting the new widget. ***Figure 27*** shows the result of selecting the "***button***" widget, copying it, and pasting the copy in the same window.
|
||||
|
||||
|
||||
|
||||
**Figure 27**
|
||||
|
||||
Copy/Paste within one project is generally straightforward because the resources that might be required by the copied widget(s) are always present when you are working within one project. However, if you copy a widget from project A and paste that widget into project B, some problems with resource dependencies can arise.
|
||||
|
||||
When you copy widget(s) within Studio, the Studio application makes a list of the resources required by the copied widgets, and generates a portable resource dependency table in the form of XML which is copied to the windows clipboard, along with the actual copied widget information. When you paste the widget(s) into a different project, Studio first examines the resource dependency list and adds the needed resources to the open project if they do not already exist. Studio identifies matching resources by the resource ID names, and for string resources Studio also compares the string content. If matching resources are found, Studio updates the resource IDs of the pasted widgets to properly use the resources in the new project. If the resources are not found, they are added.
|
||||
|
||||
When Studio adds a resource to your project as part of a widget paste operation, Studio is really adding a link to the resource in the case of font and pixelmap resources. This link is generated from the source project, and you will receive warning messages if those resources cannot be found relative to the project location of the project into which you are pasting. The resource links will be added to the project regardless, but you may need to manually copy fonts and image files into the proper locations under your new project tree to eliminate resource loading errors. Studio does not copy .ttf, .png, or .jpg files from one location to another.
|
||||
|
||||
The easy way to avoid any problems in this regard is to keep a consistent directory structure between projects that you want to share. If you want to move things from Project A to Project B easily, then keep the graphics images and fonts used by both projects in a consistent sub-directory of each project folder.
|
||||
|
||||
## Changing Z-Order
|
||||
|
||||
Widgets can easily be moved in front of or behind other widgets. This is accomplished by selecting the widget and selecting either the ***Move to Front*** or ***Move to Back*** buttons on the ***Tool Bar***. ***Figure 28*** shows the moving the second button to the back.
|
||||
|
||||
|
||||
|
||||
**Figure 28**
|
||||
|
||||
## Assigning Colors, Fonts, and Pixelmaps
|
||||
|
||||
In addition to selecting colors, fonts, and pixelmaps in the Properties View for a selected widget, a shorthand drag-and-drop method of assigning resources to widgets is also supported. To use this feature, simply left click on a resource such as a color of font in the resource view, and drag the resource over the desired widget in the target view. Drop the resource by releasing the left mouse button over the widget.
|
||||
|
||||
Color resources are always assigned to the widget normal background color when using the drag and drop method. Other colors such as selected color or selected text color must be assigned using the Properties View.
|
||||
|
||||
Similarly, pixelmap resources are assigned to the "normal" or "fill" pixelmap field of a widget that supports pixelmap display. To assign other fields to a widget that supports multiple pixelmaps, you must use the Properties View.
|
||||
|
||||
## Using templates
|
||||
|
||||
Any screen or collection of child widgets that you design in Studio can be used as a template for new screens and new child controls. You can base a template on a Window type widget, which is the normal use case, or any other widget types. Using a template is similar to copying and pasting a widget, except anything derived from a template is automatically modified when the template upon which it is based is modified. You are not allowed to modify the template widget properties when working with a derived screen or inherited instance of the template. However, when you modify the template properties in any way, all instances that reference that template are automatically updated, since they are derived from that template.
|
||||
|
||||
Another advantage of using templates for repeated items is that the Studio generated specifications file will usually be smaller in size than if you recreated the repeating items each time they are used.
|
||||
|
||||
To designate that a screen or collection of child widgets is to be used as a template, you turn on the "Template" checkbox in the widget properties view. Once you turn on the "Template" checkbox, the template widget will appear in the ***Insert|Template*** pull down menu(s).
|
||||
|
||||
As an example of using a template, you might define a window that is used as a button bar. This window may itself contain have several child buttons, and this button bar is used frequently on various screens. You can define a small standalone window within your Studio project that holds the required child buttons, and give this window the name "button_bar". Then select this window and turn on the "Template" property. Next select a screen on which you wish to add this button bar. Use the Insert|Template|button_bar menu command to insert an instance of the button_bar window on your screen. Note that you can reposition the button bar, but you are not allowed to change most properties. However you can use the button_bar widget (and any children) just like any other pre-defined GUIX widget types. To modify the button_bar, you must select the button_bar template to make your changes.
|
||||
|
||||
Another example of a typical template usage is an application that includes many similar screens. For example the application might have 10 different screens that all share a common title bar, fill color, size, etc. In this case, you could define a template screen that includes your title bar child widgets and configures the screen size, fill color, and other properties. Once this template screen is defined, you can then derive your 10 different screens from this template. When you use the Insert|Template|\<base_screen> menu command, your screen will start out with all the child widgets and settings of your template screen. Note that each screen you derive from the template screen is not a copy of the template, but is truly a derived instance of the template screen. You can then customize each derived screen to hold whatever additional content is required.
|
||||
|
||||
Note that in addition to saving size the generated specifications file, using templates can make it easier to manage changes to your application appearance. In the above example, suppose you are required to change the background color of your 10 similar screens. Rather than being required to select each screen and change the fill color settings, you only have to select the base template and change its fill color, and this change will immediately be reflected in all derived screens.
|
||||
|
||||
A further comment regarding templates: you must insure that the event processing flow is maintained, meaning that if you provide an event handler for both a base screen (for handling the common widget events) and for a derived screen, the derived screen event handler should call the base_screen event handler in the default case. This will allow the base screen event handler to process events generated by widgets common to all screens derived from this template base.
|
||||
|
||||
## Record and Playback Macro
|
||||
|
||||
Macro record and playback functions help you record and playback
|
||||
keystrokes and mouse events.
|
||||
|
||||
Recording to a macro file is accomplished by selecting the ***Record Macro*** toolbar button or the menu selecting ***Edit, Record Macro***. GUIX Studio will presents the ***Record Macro*** dialog which allows you to specify the pathname for your macro file. After making this selection, click the ***Record*** button to start recording. After you have finished recording, again select the ***Record Macro*** toolbar button or use the pull-down menu selecting ***Edit, End Macro*** to end macro recording.
|
||||
|
||||
Playback of a macro file is accomplished by selecting the ***Playback Macro*** toolbar button using the main pull-down menu to select the ***Edit, Playback Macro*** command. GUIX Studio presents the ***Playback Macro*** dialog, which allows you to specify the previously recorded macro file to be run.
|
||||
|
||||
When recording macros that choose input or output files, such as adding a font or image, it is important to use the keyboard to type the file name, rather than using the mouse to select from the file browser. Since the macro recorder records mouse and keyboard events, and since your file browser may change over time, it is more reliable to type the filename than to select the file graphically.
|
||||
|
||||
## Zooming Target View
|
||||
|
||||
Zoom In function help you to get a close-up view of the target screen.
|
||||
|
||||
You are able to choose the percentage zoom setting that you want in ***Configure|Target View|Zoom*** menu option. The ***Tool Bar*** also has buttons for zoom in/out.
|
||||
|
||||
## Grid/Snap Settings
|
||||
|
||||
The ***Grid and Snap Settings*** dialog contains some settings and options for grid and snap. ***Figure 29*** shows the ***Grid and Snap Setting*** dialog when menu ***Configure|Target View|Grid/Snap*** is selected.
|
||||
|
||||
|
||||
|
||||
**Figure 29**
|
||||
|
||||
Turn on ***Show Grid*** option will display grid on target screen, you can specify grid increment (in pixels) in ***Grid Spacing*** field and minimum snap distance in ***Snap Spacing*** field. The ***Snap to Grid*** and ***Snap to Widget*** options help you to get the proper position for a widget. Turning on these options activate snaps.
|
||||
|
||||
When ***Snap to Grid*** option is enabled:
|
||||
|
||||
- If you drag an object with the mouse in target view, the object center would snap to grid position.
|
||||
- If you drag the edge of an object to resize, the edge that you are dragging would snap to grid position.
|
||||
- If you select an object and use up/left/down/right keys, selected widget would move by snap distance.
|
||||
|
||||
When ***Snap to Widget*** option is enabled:
|
||||
|
||||
- The selected widget would snap to the suggested aligned position when it is moving near a position that would align with another widget.
|
||||
- ALT key could be used to disable "Snap to Widget" feature temporarily.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: GUIX Studio Generated Code
|
||||
description: When you are done editing your screens and resources, GUIX Studio produces a set of output files that can be incorporated into your embedded application.
|
||||
---
|
||||
# Chapter 6: GUIX Studio Generated Code
|
||||
|
||||
When you are done editing your screens and resources, GUIX Studio produces a set of output files that can be incorporated into your embedded application. The output files are generated by selecting ***Generate Resource Files*** and ***Generate Specifications*** from the Project menu item. The 'c' language source code files generated by GUIX Studio are intended to be compiled and linked with the embedded application source code. If a binary format resource file is produced, this file should be programmed to a non-volatile storage area on the target and the GUIX API function gx_binres_theme_install should be used to install the binary resources at runtime.
|
||||
|
||||
The user's embedded application code makes references to the code generated by GUIX Studio. Furthermore, the GUIX Studio generated code expects all custom widget drawing, event handling, and memory allocation functions specified in the project to be defined in the user's embedded application code. If they are not, link errors will be present when building the application.
|
||||
|
||||
> **Note:** The user should never have to modify the code generated by GUIX Studio and should resist doing so. All UI modifications should be made in the associated GUIX Studio project. This will keep the project synchronized with the embedded application.
|
||||
|
||||
## Generating Resource Files
|
||||
|
||||
Resource files generated by GUIX Studio contain preset data structures that define all of the GUIX Studio resources (colors, fonts, pixelmaps, and strings), which is effectively all the resources defined in the ***Resource View*** of the project. These resource files can be generated in source code or binary forms.
|
||||
|
||||
By default, there are two files generated, one file is a standard C source code file and the other is a C header file that provides external references and constants that are necessary for the application code to access the GUIX resources defined in the project. The file names are of the form:
|
||||
|
||||
**{*project-name*}_resources.h**
|
||||
|
||||
**{*project-name*}_resources.c**
|
||||
|
||||
For example, the Resource files created for the "***simple***" GUIX Studio project are:
|
||||
|
||||
**simple_resources.h**
|
||||
|
||||
**simple_resources.c**
|
||||
|
||||
Generating the Resource files is accomplished by selecting ***Generate Resource Files*** option in the ***Project*** menu option. The destination of the resource files is specified in the ***Configure Project*** dialog, which is accessible via the ***Configure Project/Displays*** option in the ***Configure*** menu item.
|
||||
|
||||
For Pixelmap and Font resources, you can specify a custom output filename for each pixelmap and font in the associated resource editing dialogs. This feature allows you to put very large resources in distinct files, rather than putting all resources in one common output file. If you do not specify an overridden filename for a font or pixelmap resource, those resources are written into the common
|
||||
resource file.
|
||||
|
||||
If you prefer to use binary resources, you can specify either raw or standard s-record output format. Binary resources are not compiled or linked with the application code, but are instead loaded at runtime using the gx_binres_them_load() API. This API service builds resource tables that point to your resources stored in non-volatile memory. You can then install these resources with a particular display using gx_display_theme_install();
|
||||
|
||||
## Generating Specification Code
|
||||
|
||||
The Specification files generated by GUIX Studio contain all the C code to create the UI designed in GUIX Studio. This code also references the Resource files generated for this project. The user's application code will make calls to this code to actually create the UI objects defined in the project. Furthermore, the user's application code contains all custom widget drawing, event handling, and memory allocation functions specified in the project. By default, there are two files generated, one file is a standard C source code file and the other is a C header file that provides external references and constants that are necessary for the application code to access the
|
||||
GUIX Studio Specifications. The file names are of the form:
|
||||
|
||||
**{*project-name*}_specifications.h**
|
||||
|
||||
**{*project-name*}_specifications.c**
|
||||
|
||||
For example, the Specification files created for the "***simple***" GUIX Studio project are:
|
||||
|
||||
**simple_specifications.h**
|
||||
|
||||
**simple_specifications.c**
|
||||
|
||||
Generating the Specification files is accomplished by selecting ***Generate Specification Files*** option in the ***Project*** menu option. The destination of the Specification files is specified in the ***Configure Project*** dialog, which is accessible via the ***Configure Project/Displays*** option in the ***Configure*** menu item.
|
||||
|
||||
## Integrating with User Code
|
||||
|
||||
Integrating the Resource and Specification files generated by GUIX Studio is straightforward, simply follow these steps:
|
||||
|
||||
1. Either copy or make the Resource and Specification files accessible via path settings to the embedded build environment
|
||||
2. Add all Resource and Specification files to embedded IDE project or makefile
|
||||
3. Ensure the application embedded code calls the necessary functions to initialize and create the UI contained in the Resource and Specification files
|
||||
4. Ensure the application embedded code contains all necessary custom widget drawing, event handling, and memory allocation functions
|
||||
5. Build the application (compile and link)
|
||||
6. Execute the application!
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
title: Defining Screen Flow
|
||||
description: GUIX Studio supports automatic generation and execution of screen transition logic.
|
||||
---
|
||||
# Chapter 7: Defining Screen Flow
|
||||
|
||||
GUIX Studio supports automatic generation and execution of screen transition logic. The user defines the screen transition logic by creating and editing a graphical screen flow diagram. When a screen flow diagram is added to the project, it enables two important features: 1) The application can be executed from within the Studio environment and 2) Studio automatically generates event handlers and screen transition logic to implement the designated screen flow within the generated specifications.c file, removing this burden from the application program.
|
||||
|
||||
Running the application on your desktop from within the Studio environment is a handy feature which saves time in that you are not required to go through a compile/link cycle to execute your application. There are of course limitations to what can be done without compiling the application. Custom drawing functions, custom event handlers, and complex event handling are not available when running the application from within the GUIX Studio environment. Still, this capability allows you to auto-generate screen transition logic, and program animations to be executed to transition from one screen to another. These effects and animations can be observed directly from within the GUIX Studio environment.
|
||||
|
||||
Note that when you define screen flow, triggers, and actions which we will describe in the following paragraphs, you are not only enabling the execution of your UI from within the Studio environment, but you are also enabling GUIX Studio to generate logic within your specifications file that will handle events and take actions based on those events, such as transitioning from one screen to another.
|
||||
|
||||
## Configuring Screen Flow
|
||||
|
||||
Before an application can be executed from within the Studio environment a few things must be defined. First, the top level screen or screens that should be displayed at program startup must be indicated by selecting the "Visible at Startup" property in the Studio properties view. This flag indicates that this screen should initially be displayed when the program starts. More than one screen can have this designation if desired.
|
||||
|
||||
After defining the screen(s) which are visible at startup, the user can define how the UI application will flow from screen to screen. GUIX Studio provides a graphical screen flow diagram to define screen transition logic. Simply select the menu selection ***Configure, Screen Flow*** to bring up screen flow edit dialog, see the screen shot in ***Figure 30***.
|
||||
|
||||
|
||||
|
||||
**Figure 30**
|
||||
|
||||
Each top-level screen defined in the project will be shown as a box showing the screen name. This box is a placeholder representing each top-level screen defined in the project. These boxes can be moved and resized as desired. When a transition from one top-level screen to another has been defined, a connection line with an arrow head between two screens will be shown to indicate transitions from one screen to another.
|
||||
|
||||
The tree view in left-side of the screen-flow diagram shows each top-level screen and you are able to select which top-level screens should be drawn in the screen-flow diagram.
|
||||
|
||||
The screen-flow diagram is scrollable. You are able to drag any screen block down and right outside the visible area to enlarge the scrollable window. Once your scrollable window is enlarged, you are able to zoom out to make it fit the visible area by scrolling the mouse wheel down. If the scrollable window is zoomed out, you are able to make it big enough to hold all of blocks by scrolling the mouse wheel up.
|
||||
|
||||
To define transitions for a screen, right click on the placeholder for that screen to bring up a Edit Trigger List dialog, see ***Figure 31***.
|
||||
|
||||
|
||||
|
||||
**Figure 31**
|
||||
|
||||
The trigger edit dialog list the events that the user has defined that will trigger a screen transition, which is why we call these events triggers. Triggers are normally signals generated by one or more child widgets of the selected screen.
|
||||
|
||||
To define a new trigger, select the ***Add New Trigger*** button in the Edit Trigger List dialog to bring up Add Trigger dialog shown in ***Figure 32***.
|
||||
|
||||
|
||||
|
||||
**Figure 32**
|
||||
|
||||
You are able to define the event type that will trigger a new set of actions, and define the actions that will be executed when that trigger event is received.
|
||||
|
||||
Once you define the event type that you want to use to trigger a new animation screen transition, save this new trigger and it will be displayed in the Edit Trigger List dialog.
|
||||
|
||||
You can modify this event (without modifying the related actions to be taken) by selecting the event in the Edit Trigger List dialog and selecting the ***Edit Trigger Event*** button.
|
||||
|
||||
Likewise, you can remove any trigger event from the list by selecting the event and clicking on the ***Delete Selected Trigger*** button.
|
||||
|
||||
To specify the animation or screen transition that should occur based on a particular trigger event, select that trigger event and click the ***Edit Action(s)*** button. Note that you can fire off more than one action based on each defined trigger.
|
||||
|
||||
The **Edit Action(s)** button brings up the Edit Actions for Trigger dialog, shown in Figure 33:
|
||||
|
||||
|
||||
|
||||
**Figure 33**
|
||||
|
||||
This dialog allows you to define any number of actions to implement based on this trigger event. You can give each action a meaningful name to help you associate each action definition with a visual animation or transition. In the example above, we defined two actions named "fade_in_text_screen" and "fade_out_button_screen".
|
||||
|
||||
The define a new action to implement, click the Add New Action button, which brings up the Select Action dialog, Figure 34:
|
||||
|
||||
|
||||
|
||||
**Figure 34**
|
||||
|
||||
Available action types include:
|
||||
|
||||
- **Animation**: Start an animation with specified information.
|
||||
- **Attach**: Attach the target screen to the parent screen, if the parent screen is not specified, the target screen will be attached to the root window.
|
||||
- **Detach**: Detach the target screen from its parent.
|
||||
- **Hide**: Hide the target screen.
|
||||
- **Screen Stack Pop**: Pop a screen from the internal screen stack.
|
||||
- **Screen Stack Push**: Push a screen pointer to the internal screen stack.
|
||||
- **Screen Stack Reset**: Remove all screen pointers from the internal screen stack.
|
||||
- **Show**: Show the target screen.
|
||||
- **Toggle**: Attach the target screen to the current screen's parent, and detach the current screen from its parent.
|
||||
- **Window Execute**: Modally executes the target screen.
|
||||
- **Window Execute Stop**: Exit modally execution of the current screen.
|
||||
|
||||
Once you have defined an action to take based on the selected trigger event, that action will be displayed in the Edit Actions for Trigger dialog. You can select this action to modify the parameters of that action as shown in Figure 35.
|
||||
|
||||
|
||||
|
||||
**Figure 35**
|
||||
|
||||
If the action type is an animation, a set of animation parameters are displayed on the right to allow you to define a slide and/or fade type animation to be executed. When an animation action is completed, you can also determine if the animation should be automatically detached from it's parent and/or pushed to the internal screen stack, which is often useful when defining multi-layer menu systems.
|
||||
|
||||
For slide and fade animations, you can also define the Easing Function to use by Selecting the Easing Func Select button. Easing functions are various curves designed to more closely mimic real life movement events. Selecting this button brings up the **Select Easing Function** dialog, Figure 36:
|
||||
|
||||
|
||||
|
||||
**Figure 36**
|
||||
|
||||
If you are defining multiple actions to associate with one trigger event, it can be useful to assign each action a meaningful name. Action names must follow C syntax naming rules, as these names will be used within the generated specifications file to define event and action tables.
|
||||
|
||||
When you define trigger events and actions within GUIX Studio, automated event handlers are generated within your project specifications file to handle these events and execute the specified actions. This means that you do NOT need to handle these events in your application code, although the trigger events are still passed to any custom event handlers you have defined. In other words the Studio generated event handlers augment, rather than replace, your own custom event handlers.
|
||||
|
||||
## Running the Application
|
||||
|
||||
Once startup screens and a screen flow diagram have been created, you can run your application within Studio by selecting the "Run Application"
|
||||
|
||||
|
||||
|
||||
button on the toolbar, selecting Edit | Run Application from the project menu, or by selecting the Run button at the bottom of the Edit Screen Flow dialog.
|
||||
|
||||
When you run the application, you will see the screen(s) you have designated as "Visible At Startup" display within a new window. The child widgets on these screen are fully operational. You can click on buttons, operate sliders and scroll wheels, etc.. If you have defined custom drawing functions or customer event handling for any of these widgets, you will of course NOT see this when running the application in this mode. But if you have defined a screen flow diagram with trigger events and actions, those triggers will be operational and your screens will transition as you have defined, including any animations that you may have defined.
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: Notes on Editing Specific Widget Types
|
||||
description: Detailed comments describing editing methods for certain complex widget types.
|
||||
---
|
||||
# Chapter 8: Notes on Editing Specific Widget Types
|
||||
|
||||
GUIX Studio allows the user to easily create and modify GUIX widgets that will compose the application UI screens. Most of these editing methods are intuitive and obvious. For example, to resize a widget you can select the widget with the mouse and drag the widget borders. You can also directly type into the left/top/width/height property fields of the selected widget.
|
||||
|
||||
Certain widget types require a more advanced editing process, because these widgets are themselves a bit more sophisticated in their feature support.
|
||||
|
||||
This chapter provides notes on the more advanced editing features for these more complex widget types. These notes will expand as the features of GUIX Studio advance along with the widget types provided within the GUIX library.
|
||||
|
||||
## Rich Text View
|
||||
|
||||
This widget is used to display rich text that supports inline text formatting codes. These formatting codes include bold, italic, and several others. To begin, right-click on the selected parent from the *Project View* or *Target View* and select menu **Insert/Text/Rich Text View** to insert a rich text view widget.
|
||||
|
||||
In addition to the standard set of properties supported by all widget types, the Rich Text View widget type supports additional properties.
|
||||
|
||||
### Additional Properties
|
||||
|
||||
| Property | Meaning |
|
||||
|----------|---------|
|
||||
| Text Align | Default text alignment |
|
||||
| Normal Font| Default text font |
|
||||
| Bold Font | Text font for text tagged as bold |
|
||||
| Italic Font| Text font for text tagged as italic|
|
||||
| Bold Italic Font| Text font for text tagged as bold and italic |
|
||||
| Private Text Copy | Should be checked if the widget is to keep its own private copy of any text assigned |
|
||||
| Whitespace | Width of margin between the widget and the displayed text, in pixels. |
|
||||
| Line Space | Space between two lines of the text, in pixels. |
|
||||
|||
|
||||
|
||||
### The Rich Text formatting codes
|
||||
|
||||
The following format codes are supported for text formatting.
|
||||
|
||||
|Tag|Meaning|
|
||||
|---|---|
|
||||
|\<b>\</b> | Render text font with user specified bold font ID|
|
||||
|\<i>\</i> | Render text font with user specified italic font ID|
|
||||
|\<u>\</u> | Render underlined text|
|
||||
|\<f GX_FONT_ID>\</f> | Render text using the specified font ID. |
|
||||
|\<c GX_COLOR_ID>\</c> | Render text using the specified color ID|
|
||||
|\<hc GX_COLOR_ID>\</hc> | Render text using the specified background color ID|
|
||||
|\<align left/right/center>\</align> | Assign text alignment|
|
||||
|||
|
||||
|
||||
There are two ways to edit the rich text string from within GUIX Studio:
|
||||
|
||||
- Use the Edit Rich Text dialog, which is the recommended and simplest editing method.
|
||||
- Use the String Table Editor dialog, which allows you to manually insert the formatting tags shown in the preceding table.
|
||||
|
||||
After selecting a Rich Text View widget in the *Target View*, select the **Edit Rich Text** button in the *Properties View* to invoke the rich text edit dialog, shown in Figure 8.1.
|
||||
|
||||
|
||||
|
||||
**Figure 8.1**
|
||||
|
||||
The left pane is the rich text edit field. You can use the toolbar icons to help insert tags you require. Select any block of text in the edit field, and then select the toolbar buttons to apply the required styles and colors to the selected text block. The Edit Rich Text dialog is an easy way to insert the formatting codes into the test string. You can also insert these tags manually or even generate them at runtime if needed.
|
||||
|
||||
The Right pane is the widget preview to show how the text is rendered in the target view. The background color of the widget preview is fixed, which may not match the widget's assigned background color in the target view.
|
||||
|
||||
Resource ID names are used in rich text to reference specific font or color resources. If the resource name of a font or color is changed after it has been referenced by the rich text string, GUIX Studio will automatically update the rich text string to reflect the resource name changes. On the other hand if you delete a font or color resource that is referenced by a rich text widget, you must edit the affected rich text manually to remove or change the resource ID names that have been deleted.
|
||||
|
||||
When you select the Save button in this dialog, the rich text string you have defined is added to the project string table.
|
||||
|
||||
## String Scroll Wheel
|
||||
|
||||
A string scroll wheel widget supports the display of an array of strings. These strings may be dynamically assigned, or, in the case that the application supports multiple languages, the assigned strings can be pulled from the active string table.
|
||||
|
||||
The string scroll wheel widget supports an array of strings. The String Scroll Wheel Edit dialog, shown in Figure 8.2, is provided to allow the user to assign this array of strings.
|
||||
|
||||
|
||||
|
||||
**Figure 8.2**
|
||||
|
||||
To invoke this dialog, select a string scroll wheel widget within the *Target View* or the *Project View*. Once this widget type is selected, the *Properties View* will include an **Edit Strings** button. Select this button to invoke the String Scroll Wheel Edit dialog.
|
||||
|
||||
To assign a string for each text index, you can either select a string ID from the drop-down list, or you can type a new string value in the Text field on the right. When you are done with your changes, any new or modified strings are saved to the active string table.
|
||||
|
||||
## Sprite
|
||||
|
||||
A sprite widget is used to display a sequence of images to provide an animation effect. A sprite widget requires a frame list, which is an array of image IDs and unique parameters applied to each image in the frame. To build this frame list for the sprite widget the Edit Sprite Frames dialog, shown in figure 8.3, is provided:
|
||||
|
||||
|
||||
|
||||
**Figure 8.3**
|
||||
|
||||
To invoke this dialog, select a sprite widget within the *Target View* or the *Project View*. Once this widget type is selected, the *Properties View* will include an **Edit Framelist** button. Select this button to invoke the Edit Sprite Frames dialog.
|
||||
|
||||
The *Total number of Sprite Frames* field is an input field allowing you to enter the integer total number of frames to be displayed by the sprite widget. Images can be reused within the frame list, meaning not every image must be unique.
|
||||
|
||||
The *Import Frames* button allows you to import a bunch of frames from pixelmap folders. Figure 8.4 shows the **Import Sprite Frames** dialog. You can select a folder from left, and then choose pixelmaps you'd like to import in the right.
|
||||
|
||||
|
||||
|
||||
**Figure 8.4**
|
||||
|
||||
The *Sprite Frame ID* field is a frame index selection value that ranges from 1 to Total number of Frames. Increment and Decrement this value to move from one sprite frame to the next.
|
||||
|
||||
The *Apply to All Frames* option applies frame property changes to all the sprite frames.
|
||||
|
||||
Each sprite frame has several parameters. The first is the Background Operation. This field mimics the capabilities of the popular GIF animation format. The choices here include:
|
||||
|
||||
- No Operation, which means the current frame image is drawn over the previous frame image.
|
||||
- Restore First Pixel-map, which means the index 1 pixel-map is drawn before the current pixel-map and
|
||||
- Solid Color Fill, which means the sprite background is filled with the sprite background color before the current frame is drawn.
|
||||
|
||||
The *Pixel-map ID* field allows you to select any pixel-map previously added to the project resources. The same pixel-map ID can be used for multiple frames. For example your sprite animation might utilize movement of the image (using the x and y offset fields) instead of or in addition to using different sprite images.
|
||||
|
||||
The *Alpha value* field is applied to the entire pixel-map drawing. This field only has an effect when running at 8 bpp color depth and higher. Alpha value 0 is fully transparent, and alpha value 255 is opaque.
|
||||
|
||||
You can specify an offset within the sprite frame at which the current pixel-map will be drawn using the Frame x-offset and Frame y-offset fields. In other words, each image drawn does not have to be the full size of the sprite widget.
|
||||
|
||||
The Delay period specifies the time to delay before moving to the next sprite frame. This value is in ticks, which for the default GUIX/ThreadX timer configuration each tick represents 50 ms.
|
||||
|
||||
When you save your changes in the Edit Sprite Frames dialog, GUIX Studio is able to generate the complete frame list array as part of the output specifications file generation.
|
||||
|
||||
### Assign a sprite widget with GIF resource
|
||||
You can add a GIF resource to **Pixelmap** resource group and assign the GIF resource to the sprite widget directly. After GIF resource is set, a frame list will be automatically generated, you can further edit each frame of the frame list through the sprite edit dialog:
|
||||
|
||||
|
||||
|
||||
**Figure 8.5**
|
||||
@@ -0,0 +1,92 @@
|
||||
---
|
||||
title: GUIX Studio Command Line
|
||||
description: GUIX Studio provides command-line invocation that is useful for build pipelines that are required to update the Studio-generated output files.
|
||||
---
|
||||
# Chapter 9: GUIX Studio Command Line
|
||||
|
||||
GUIX Studio supports command-line invocation, which is useful for build pipelines that are required to update of the Studio-generated output files.
|
||||
|
||||
## Command-Line Usage
|
||||
|
||||
**Usage:** guix_studio \[OPTION\] \[ARGUMENT\]
|
||||
|
||||
Open the *.gxp* project.
|
||||
|
||||
Open the Studio project and generate desired output files.
|
||||
|
||||
|
||||
**Examples:**
|
||||
|
||||
`guix_studio.exe demo.gxp`
|
||||
Open "demo.gxp" project
|
||||
|
||||
`guix_studio.exe –p demo.gxp`
|
||||
Open "demo.gxp" project
|
||||
|
||||
`guix_studio.exe –n –p demo.gxp`
|
||||
Generate all output files of demo.gxp project.
|
||||
|
||||
`guix_studio.exe –n –r –p demo.gxp`
|
||||
Generate resource files of demo.gxp project.
|
||||
|
||||
`guix_studio.exe -x resource.xml -b`
|
||||
Generate binary resource file from a resource project resource.xml.
|
||||
|
||||
|
||||
## Command-Line Options
|
||||
|
||||
***-n --nogui***
|
||||
|
||||
The "nogui" option. Tell GUIX Studio to run without starting the windowing UI interface.
|
||||
|
||||
***-o pathname, --log***
|
||||
|
||||
Log option, specify a log file.
|
||||
|
||||
***-b, --binary***
|
||||
|
||||
Binary resource option. Produces a binary resource file rather than a C file.
|
||||
|
||||
***-d display1, display2, --display***
|
||||
|
||||
Display names option. If this option is used, then only the specified display names are included in any generated resource or specification files. If this option is not used, all displays are included.
|
||||
|
||||
***-t theme1, theme2, --theme***
|
||||
|
||||
Theme name(s) option. If this option is used, then only the specified theme names are included in any generated resource or specification files. If this option is not used, all themes are included.
|
||||
|
||||
***-l language1, language2, --language***
|
||||
|
||||
Language name(s) option. If this option is used, the specified language names are included in the generated resource or specification files. Otherwise all language names are included.
|
||||
|
||||
***-r [filename], --resource***
|
||||
|
||||
The resource option, specifies that Studio should produce a resource file for previously designated display(s), theme(s), and language(s).
|
||||
|
||||
***-s [filename], --specification***
|
||||
|
||||
The specification option, specify that studio should produce a specification file for designated display(s), theme(s), and language(s).
|
||||
|
||||
***-p project_pathname, --project***
|
||||
|
||||
Project pathname option, specify the example project to be loaded.
|
||||
|
||||
***-i [pathname], --import***
|
||||
|
||||
Import string from xliff or csv format file.
|
||||
|
||||
***--big_endian***
|
||||
|
||||
Generate resource data in big-endian format.
|
||||
|
||||
***--no_res_header***
|
||||
|
||||
Not generating resource header.
|
||||
|
||||
***-x [pathname], --xml***
|
||||
|
||||
Specify the input resource XML file.
|
||||
|
||||
***--output_path pathname***
|
||||
|
||||
Specify the output directory. If not specified, the project directory will be used for the output files.
|
||||
@@ -0,0 +1,106 @@
|
||||
---
|
||||
title: GUIX Studio Quick Start Guide
|
||||
description: This guide provides a brief introduction into the usage of the GUIX Studio application, the Microsoft Windows-based rapid UI development environment specifically designed for the GUIX runtime library from Eclipse Foundation.
|
||||
---
|
||||
# GUIX Studio Quick Start Guide
|
||||
|
||||
This guide provides a brief introduction into the usage of GUIX Studio. GUIX Studio is a Windows-based UI design application designed for use with the GUIX runtime library from Eclipse Foundation.
|
||||
|
||||
It is intended for the embedded real-time software developer using the ThreadX Real-Time Operating System (RTOS) and the GUIX UI run-time library. The developer should be familiar with standard ThreadX and GUIX concepts.
|
||||
|
||||
## Summary
|
||||
|
||||
GUIX Studio includes everything you need to create, build, and run your own graphical interface design.
|
||||
If you are evaluating GUIX Studio, the evaluation kit is designed to allow you to build and run your GUIX design as a standalone Windows desktop application for test and evaluation purposes. Because GUIX is designed for use on nearly any embedded target capable of graphical output, the work you do and the designs you create on the desktop can always be compiled and run on your embedded target without changing any of your application software.
|
||||
The GUIX Studio installer places several components on your development system:
|
||||
|
||||
- The GUIX Studio application.
|
||||
- Several GUIX example projects.
|
||||
- All graphics resources and fonts used in the example projects.
|
||||
- Solution files and project files for building in a Windows desktop environment using the Microsoft Visual Studio IDE.
|
||||
- Pre-built GUIX and ThreadX libraries for Win32, allowing you to build and run your own applications on your PC.
|
||||
- GUIX and ThreadX API header files.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The GUIX Studio installer includes several simple example projects, and we expect that you will begin by modifying, building, and running these examples as you learn how to use the GUIX Studio application. In order to build and run the examples on the Windows desktop, you will need a Visual Studio compiler. These tools can be downloaded from the following location:
|
||||
|
||||
https://www.visualstudio.com/downloads/download-visual-studio-vs#DownloadFamilies_4
|
||||
|
||||
If you do not have the Visual Studio developer tools installed, you can still kick the tires and use the GUIX Studio application to create your own interface design and examine the source code produced. However you will not be able to build and run your design as a standalone application.
|
||||
|
||||
## Running the Examples
|
||||
|
||||
After running the GUIX Studio installer, you will find several example Studio project and build files are included in the installed contents. To verify that your desktop tools are installed and working correctly, we recommend that you begin by building and running each of the provided examples as-is. We will refer to your installation directory as \<root>, in which case you should use your file browser and browse to \<root>/GUIX_Studio_6.x/examples. Within this directory you should see several simple example programs such as demo_guix_calculator, demo_guix_car_infotainment, demo_guix__home_automation, demo_guix_widget_types, and others.
|
||||
|
||||
## Building an example
|
||||
|
||||
You should find a subdirectory named *build* within each example folder. This direction includes pre-configured projects for each supported toolchain. For example, you can browse to \<root>/GUIX_Studio_6.x/examples/thermometer/build/vs_2019 and you will find a pre-configured Visual Studio solution file and project file ready to be loaded and run in the Visual Studio IDE.
|
||||
|
||||
We recommend that you start the Visual C++ IDE and open at least one of these examples. Press the \<F7> key to build the example project, and press the \<F5> key to run the program after it builds successfully. You should now see a GUIX user interface running within a Windows window.
|
||||
|
||||
## Designing and Running your own User Interface
|
||||
|
||||
This quickstart guide is not a replacement for the GUIX Studio User Guide or the GUIX User Guide, but we will show you enough to get started and encourage you to continue by referring to the GUIX Studio User Guide for more detailed information.
|
||||
|
||||
There are two methods of creating and modifying your own user interface. You can study the GUIX library programming manual and use the GUIX API directly from within your application software to fully implement your design. More often, you will use the GUIX Studio application to do most of the work of design and layout of your screen elements, and then complete the event handling and other application logic required to make your user interface perform real work.
|
||||
|
||||
Each of the provided examples was created using the GUIX Studio interface design application. You should have an icon on your desktop for GUIX Studio 6.x.x.x after running the GUIX Studio installer. Start GUIX Studio now and open the project named "demo_guix_widget_types\guix_widget_types.gxp". The *widget_types* demo is an example project that demonstrates several variations of the most common GUIX widget types.
|
||||
|
||||
Now that you have a project open, click "+" to open the tree node named "Primary" in the Project View in the upper left corner of the IDE, and click on the top-level window within this folder named "Menu_Screen". Your project should not appear as shown below:
|
||||
|
||||
|
||||
|
||||
## GUIX Studio Views
|
||||
|
||||
The GUIX Studio IDE is composed of several ***views***. Each view is designed to assist you in navigating through your design and making changes to that design.
|
||||
|
||||
### Project View
|
||||
|
||||
The top-left view is called the Project View. This view shows you each of the physical displays that are included in your project (most projects have only one display), and the screens and child widgets that have been designed to run on that display.
|
||||
|
||||
### Properties View
|
||||
|
||||
Below the Project View is the Properties View. As the name Properties View implies, this view allows you to modify widgets by changing various properties associated with them.
|
||||
|
||||
### Target View
|
||||
|
||||
The central display area is called the Target View. This view is a WYSIWYG display of your user interface. Because the GUIX library is drawing within the target view, this view is a pixel-accurate representation of how your design will look when executing on your embedded target. If you click on different widgets either in the Project View or the central Target View, you will see the values displayed in the Properties View change to display the properties of the widget you have selected.
|
||||
|
||||
### Resource View
|
||||
|
||||
Finally, on the right, you will see what is called the Resource View. This view allows you to select, add, delete, and modify the colors, fonts, pixelmaps, and strings included in your project.
|
||||
|
||||
## Modifying the Example
|
||||
|
||||
GUIX Studio is designed to be intuitive. To move one of the widgets shown above, you simply click on that widget in the Target View and drag it to a new location. To change the widget colors, you click on the desired widget and change the colors displayed in the Properties View. To change the font used by a text display widget, you simply click on the desired font within the Resource View and drag-and-drop the font onto the desired target widget. Float your mouse along the toolbar buttons to see quick help regarding the operation that each button performs.
|
||||
|
||||
Experiment yourself and make some minor changes to the example. For example you might drag a widget to a new location, change a window background color, or resize a button. We do not recommend deleting any widgets from the example until you gain more experience working with GUIX since deleting widgets might require associated modifications to application source code.
|
||||
|
||||
## Running the application within Studio
|
||||
|
||||
You can use the Edit | Run Application menu command (or Run Application button on the button bar) to run the application immediately within a new desktop window. Custom drawing functions and other application code will not be invoked using this method, but it does allow you to quickly navigate through your UI design and get an overall idea of the look and feel of the application, including navigation from one screen to the next.
|
||||
|
||||
## Generating Source Files
|
||||
|
||||
After making your changes, you need to invoke GUIX Studio menu commands to generate new source files for your project. You can then rebuild the example program to see your changes in action. To generate source files, use the GUIX Studio menu commands Project|Generate Resource Files and Project|Generate Specification Files (you can also right-click on the display in the Project View to execute these commands).
|
||||
|
||||
As you generate these new source files, you should observe a confirmation message telling you that the source files associated with your project have been updated. If you do not observe this confirmation message, check to make sure you have write permissions to the directory in which the project resides. You can now close the GUIX Studio application. If you have made changes to the project, GUIX Studio will ask you if you want to save those changes. Go ahead and save your changes, these examples are intended for you to use and experiment with as you learn to use GUIX Studio.
|
||||
|
||||
### Building and running the application
|
||||
|
||||
Now that GUIX Studio has generated your project output files, you can compile and link to create a standalone Win32 executable. In addition, in order to incorporate any custom drawing or event handling you have defined in your application, you need to compile and link the output files generated by GUIX Studio with your own application software. We will use the Visual C++ toolchain as an example, but exactly the same procedure is used if you are building and running for your intended target.
|
||||
|
||||
- Start the MSVC IDE, and open the solution \<root>/GUIX_Studio_5.x/examples/demo_guix_widget_types/build/vs_2019/guix_widget_types.sln.
|
||||
|
||||
- Use the \<F7> key to rebuild the solution.
|
||||
- Use the \<F5> key to run the program.
|
||||
|
||||
You should now see the running program, with the changes you made within Studio!
|
||||
|
||||
### Learning More
|
||||
|
||||
The [GUIX Studio User Guide](about-guix-studio.md) is a much more thorough guide to using GUIX Studio.
|
||||
|
||||
In addition, the [GUIX User Guide](about-guix.md) gives you much more detailed information about what is happening "Under the Hood" when your GUIX application executes. You will need to refer to both of these guides to fully utilize the capabilities of the GUIX runtime library and GUIX Studio.
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
# GUIX documentation
|
||||
|
||||
[Overview of GUIX](overview-guix.md)
|
||||
|
||||
[GUIX Studio Quick Start Guide](guix-studio-quick-start.md)
|
||||
|
||||
GUIX user guide
|
||||
- [About this guide](about-guix.md)
|
||||
- [Ch. 1 - Introduction to GUIX](chapter-1.md)
|
||||
- [Ch. 2 - Installation and use of GUIX](chapter-2.md)
|
||||
- [Ch. 3 - Functional overview of GUIX](chapter-3.md)
|
||||
- [Ch. 4 - Description of GUIX services](chapter-4.md)
|
||||
- [Ch. 5 - GUIX display drivers](chapter-5.md)
|
||||
- [GUIX example](guix-example.md)
|
||||
- [App. A - GUIX color definitions](appendix-a.md)
|
||||
- [App. B - GUIX color formats](appendix-b.md)
|
||||
- [App. C - GUIX widget styles](appendix-c.md)
|
||||
- [App. D - GUIX brush, canvas, and gradient attributes](appendix-d.md)
|
||||
- [App. E - GUIX event description](appendix-e.md)
|
||||
- [App. F - GUIX RTOS binding services](appendix-f.md)
|
||||
- [App. G - GUIX font structure](appendix-g.md)
|
||||
- [App. H - GUIX build-time configuration flags](appendix-h.md)
|
||||
- [App. I - GUIX information structures](appendix-i.md)
|
||||
- [App. J - Canvas Partial Frame Buffer Feature](appendix-j.md)
|
||||
|
||||
GUIX Studio User Guide
|
||||
- [About GUIX Studio](about-guix-studio.md)
|
||||
- [Ch. 1 - Introduction to GUIX Studio](guix-studio-1.md)
|
||||
- [Ch. 2 - Installation and Use of GUIX Studio](guix-studio-2.md)
|
||||
- [Ch. 3 - Description of GUIX Studio](guix-studio-3.md)
|
||||
- [Ch. 4 - GUIX Studio Resources](guix-studio-4.md)
|
||||
- [Ch. 5 - GUIX Studio Screen Designer](guix-studio-5.md)
|
||||
- [Ch. 6 - GUIX Studio Generated Code](guix-studio-6.md)
|
||||
- [Ch. 7 - Defining Screen Flow](guix-studio-7.md)
|
||||
- [Ch. 8 - Notes on Editing Specific Widget Types](guix-studio-8.md)
|
||||
- [Ch. 9 - GUIX Studio Command Line](guix-studio-9.md)
|
||||
- [Ch. 10 - Simple Example Project](guix-studio-10.md)
|
||||
- [Ch. 11 - Resource Project File](guix-studio-11.md)
|
||||
|
||||
[GUIX repository](https://github.com/azure-rtos/guix)
|
||||
|
||||
[Eclipse ThreadX components](../../README.md)
|
||||
- [ThreadX](../threadx/index.md)
|
||||
- [ThreadX Modules](../threadx-modules/index.md)
|
||||
- [NetX Duo](../netx-duo/index.md)
|
||||
- [GUIX](../guix/index.md)
|
||||
- [FileX](../filex/index.md)
|
||||
- [LevelX](../levelx/index.md)
|
||||
- [USBX](../usbx/index.md)
|
||||
- [TraceX](../tracex/index.md)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 684 B |
Binary file not shown.
|
After Width: | Height: | Size: 69 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.4 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 341 B |
Binary file not shown.
|
After Width: | Height: | Size: 77 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.1 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 4.9 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 443 B |
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.8 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 522 B |
Binary file not shown.
|
After Width: | Height: | Size: 9.5 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 9.0 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 362 B |
Binary file not shown.
|
After Width: | Height: | Size: 322 B |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user