AN-00117 Designer Getting Started - First Project

Description This application note shows how to create a new project, how to select the target display module, how to connect a display module to the PC, and how to compile and download a simple “Hello-world” program to the target device. This application note also introduces the basics of 4DGL (4D Graphics Language).
Supported Processor PICASO, GOLDELOX, DIABLO16
Supported Environment Designer
Difficulty Easy

File Downloads
Files

  Description

This application note shows how to program a 4D display module in the Designer environment to make it print text on the screen.

Before getting started, the following are required:

for non-gen4 displays(uLCD-xxx)

for gen4 displays (gen4-uLCD-xxx)

  • Workshop 4 IDE (installed according to the installation document)
  • 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.

This application note requires that the reader has a basic knowledge of any programming language such as C.

  Application Overview

The Designer environment enables the user to write 4DGL code in its natural form to program the display module. 4DGL is a graphics oriented language allowing rapid application development, and the syntax structure was designed using elements of popular languages such as C, Basic, Pascal and others. Programmers familiar with these languages will feel right at home with 4DGL.

 

This application note shows how to create a new project, how to select the target display module, how to connect a display module to the PC, and how to compile and download a simple “Hello-world” program to the target device. This application note also introduces the basics of 4DGL (4D Graphics Language).

 

Setup Procedure

Open a Project from the File Explorer

This document comes with a demo Designer program in a zip file.

 

In the file explorer window, extract the content of the zip file to a desired location. The content is a Designer project file.

 

The user can open the file by double-clicking on it or by selecting it from Workshop 4. Users who want to learn how to create a new Designer program, proceed to the next section.

 

Open the Example in Workshop 4

There is a shortcut for Workshop 4 on the desktop.

 

Launch Workshop 4 by double-clicking on the icon. Workshop 4 opens and displays the Recent page.

 

To load the existing project, click on Open.

 

A standard open window asks for a Designer project. Select the demo file.

 

The project opens.

 

 

How to Change the Target Display

The attached project has its target display configured to be a uLCD-32PTU. To change the target device, go to the Project menu and click on the display button.

 

The Change Display window appears. Change the target display by clicking on the display name.

 

A drop-down menu will appear. Select your new target device.

 

Click OK to confirm when done.

 

Changing the orientation is done by manually editing the code. This will be discussed later.

 

Create a New Project

Launch Workshop 4

There is a shortcut for Workshop 4 on the desktop.

 

Launch Workshop 4 by double-clicking on the icon. Workshop 4 opens and displays the Recent page.

 

Create a New Project

Workshop 4 opens and displays the Recent page.

 

To create a new project, there are two options.

Click on the top left-most icon, New.

 

 

            Or Click on the icon beside Create a new Project.

 

 

Select a Picaso Display Module

The Choose-Your-Product window appears. Select the appropriate screen and preferred orientation. The screen used in this example is a uLCD-32PTU (Portrait orientation).

 

Select the desired orientation by clicking on the display on the right part of the Choose-Your-Product window.

 

The image of the display rotates as you click it. When done, click on the next button on the lower right part of the Choose-Your-Product window.

 

Select a Diablo16 Display Module

To select a Diablo16 display module such as the uLCD-35DT in portrait orientation,

 

Select a Goldelox Display Module

To select a Goldelox display module such as the uLCD-160-G2 in landscape orientation,

 

Select Designer

 

Design the Project

The Hello-World Program

Everything is now ready to start designing a project. Workshop automatically provides the program skeleton, which contains basic parts needed to start designing an application. This is the “hello-world” program.

Hello World - Picaso

Hello World – Diablo16

 

Hello World – Goldelox

 

Define the Platform

The first line of the hello world program defines the specific target display module.

Picaso

 

Diablo16

 

Goldelox

For Goldelox display modules, the first line defines the platform or the processor.

 

Include Files

To include a source file in 4DGL, use the pre-processor directive “#inherit”. The hello world programs for the Picaso, Diablo16, and Goldelox platforms have one common include file.

 

Hexadecimal Colour Values

4DGL_16bitColours.fnc contains hexadecimal values for different colours. The user can view the contents of 4DGL_16bitColours.fnc by following the instructions below.

 

How to Open Include Files

  1. Put the cursor on the filename.

 

  1. Click the right mouse button and a menu will appear. Select the first option (Open file at Cursor).

 

  1. Workshop 4 now opens the file 4DGL_16bitColours.fnc.

 

 The file contains constants and their values. Values of constants do not change throughout the duration of the program.

Defining Constants

The file 4DGL_16bitColours.fnc contains hexadecimal values of 140 commonly used colours. Scroll down to see all the colours defined. Take note of lines 8 and 149 indicated below.

 

The figure above shows how a block of constants is declared.

The Main Function

Lines 5 to 14 make up the main function of the program.

 

Note that the block starts with

and ends with

 

This is how a function is defined in 4DGL.

Set the Orientation

Line 7 sets the orientation of the screen.

 

This line is automatically generated by Workshop when the user selects an orientation in the Choose-Your-Product window while creating a new project. Possible modes for orientations are LANDSCAPE, LANDSCAPE_R, PORTRAIT, and PORTRAIT_R. These correspond to landscape, landscape reversed, portrait, and portrait reversed, respectively.

 

To change the display orientation of an already-created project, the user has to manually edit the code. The Change Display window under the Project menu will have no effect on the already-generated code for setting the orientation.

 

Comments in 4DGL

Single-line comments in 4DGL look like as shown below.

 

Print a String

The line

will print the text “Hello World” on the screen.

The Repeat-forever Loop

Writing the lines

 

and

 

is one way of declaring a loop. A loop in a program performs instructions repetitively. The program will execute any statement between lines 11 and 12 indefinitely. Here the program actually does nothing indefinitely after printing the text “Hello World” since no instructions exist between lines 11 and 12.  If this empty loop is omitted, the program exits the main function. All of this happens so fast that the user will not even see the text “Hello World” printed on the screen.

Run the Program

Save the Project

Save the program with the desired file name first.

 

Connect the Display Module to the PC

Connect the display module to the PC using a 4D Programming Cable or a uUSB-PA5 adapter. Go to the Comms menu to check if the module is detected. The button should be blue in colour. Below is an example of how the Comms tab will look like if a uLCD-32PTU is connected to the PC.

 

Program Destination

For Picaso and Diablo16 display modules, the user has the option of downloading the program to any of the two available memory locations – RAM and Flash.  RAM is volatile and the program is lost after a power cycle. A program downloaded to Flash remains after a power cycle. Go to the Project menu and select Flash as the destination.

The Goldelox processor has a limited RAM size such that the program can be loaded to Flash only.

Compile and Download

After making sure that the device is detected, go to the Home menu and click on the Comp n’Load or Compile and Download button.

 

Workshop now downloads the program to the display module. The message box will look like as shown below after a successful download.

 

The program now runs and displays “Hello World” on the screen. Note that a µSD card is not needed here since the program does not display images from the µSD card yet.

Share: