AN-00194 Designer or ViSi 4DGL Strings Print Formats – the String and Character Format Specifiers

Description This application note shows how the “%s” and “%c” format specifiers are used together with the str_Printf(…) function. This application is intended for use in the Workshop 4 – Designer environment. The 4DGL code of the Designer project can be copied and pasted to an empty ViSi project and it will compile normally. The code can also be integrated to that of an existing ViSi project.
Supported Processor PICASO, DIABLO16
Supported Environment Designer, ViSi
Difficulty Medium

File Downloads
Files

  Description

This application note requires:

and other superseded modules which support the ViSi Genie environment

 

Visit www.4dsystems.com.au/products to see the latest display module products that use the Diablo16 processor. The display module used in this application note is the uLCD-32PTU, which is a Picaso display. This application note is applicable to Diablo16 display modules as well.

for non-gen4 displays(uLCD-xxx)

for gen4 displays (gen4-uLCD-xxx)

  • micro-SD (µSD) memory card
  • Workshop 4 IDE (installed according to the installation document)
  • Any Arduino board with a UART serial port
  • 4D Arduino Adaptor Shield (optional) or connecting wires
  • Arduino IDE

When downloading an application note, a list of recommended application notes is shown. It is assumed that the user has read or has a working knowledge of the topics presented in these recommended application notes.

  Application Overview

The application note Designer or ViSi Strings and Character Arrays explains how 4DGL strings and character arrays are stored in and accessed from memory. In that application note, the reader was also introduced to the concept of byte-aligned pointers and the use of the function str_Printf(…).

 

This application note now further explains the use of the str_Printf(…) function together with the “%s” and “%c” format specifiers.

  Setup Procedure

For instructions on how to launch Workshop 4, how to open a Designer project, and how to change the target display, kindly refer to the section “Setup Procedure” of the application note

Designer Getting Started - First Project

For instructions on how to launch Workshop 4, how to open a ViSi project, and how to change the target display, kindly refer to the section “Setup Procedure” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16

  Create a New Project

For instructions on how to create a new Designer project, please refer to the section “Create a New Project” of the application note

Designer Getting Started - First Project

For instructions on how to create a new ViSi project, please refer to the section “Create a New Project” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16

  Design the Project

The Function str_Printf(…)

To review the use of the function str_Printf(…), we start by declaring the word array buffer, which has a size of ten and the word variable ptr.

 

We now stream to buffer the literal string constant “1234”.

 

We then make the word variable ptr a byte-aligned pointer to the string inside buffer.

 

To print the string using the pointer, we write:

 

The output of the above code should be:

 

The Format Specifier “%s”

The str_Printf(…) function requires the address of the byte-aligned pointer and a format specifier as the arguments. The most commonly used format specifier is “%s”. It causes the str_Printf(…) function to print the data pointed to by the byte-aligned pointer as a string of characters. Note that the word array buffer in this case would contain the data shown below.

 

The hexadecimal values are the equivalent ASCII values of the characters. For the line

to work, the word array (buffer in this example) pointed to by the byte-aligned pointer (ptr in this example) must contain a null-terminated sequence of ASCII characters.

Automatic Advancing of the Pointer

Now consider the code snippet shown below.

 

The output of this would be:

 

The initial value of ptr is 16. This is the address of the first character in the string.

 

After the string is printed the value of ptr is now 21.

A change in the value of the pointer occurs because the function str_Printf(…) automatically advances the byte-aligned pointer as it prints the characters. In this case, since the string has four characters, the pointer is now at address 21 after the four characters are printed. So if we would insert another str_Printf(…) command as shown below.

 

The output would be

 

Note that nothing is printed since there are no character bytes starting at address 21 or the low byte of buffer[2]. To print the string again therefore, we must first reset the pointer to the beginning address of the string, like as shown below.

 

The Designer project for the discussion on the “%s” format specifier is “stringsBasics3.4dg” (attached).

 

The Format Specifier “%c”

The format specifier “%c” causes the str_Printf(…) function to go to the byte address pointed to by the pointer and print the character inside that byte memory location. To illustrate using our previous example, we write,

 

The output of this code snippet would be:

 

We see here again that the pointer is automatically advanced. To print the three remaining characters we write,

 

The output of the above snippet would be:

 

The Designer project for the discussion on the “%c” format specifier is “stringsBasics4.4dg” (attached).

 

Dynamic Construction of the Format Specifier

The format specifier argument of the str_Printf(…) function can also be a word-aligned string pointer, allowing dynamic construction of the printing format. To illustrate using one of our previous examples, we write,

 

Note that another word array, format, was declared.

 

To this the literal string constant “%s” was streamed.

 

And then format, which is essentially a word-aligned pointer to the stored string “%s”, was used as the second argument of the str_Printf(…) function.

 

The output of the above code snippet would be:

 

If we were to stream “%c” instead of “%s” to format,

 

The output would be:

The Designer project for the discussion on dynamic construction of the format specifier is “stringsBasics5.4dg” (attached). Although the examples are simple, the ability to construct a format specifier dynamically can be a powerful tool.

  Run the Program

For instructions on how to save a Designer project, how to connect the target display to the PC, how to select the program destination, and how to compile and download a program, please refer to the section “Run the Program” of the application note

Designer Getting Started - First Project

For instructions on how to save a ViSi project, how to connect the target display to the PC, how to select the program destination, and how to compile and download a program, please refer to the section “Run the Program” of the application note

ViSi Getting Started - First Project for Picaso and Diablo16

The uLCD-32PTU and uLCD-35DT display modules are commonly used as examples, but the procedure is the same for other displays.

Share: