Difference between revisions of "Getting Started"

From uGFX Wiki
Jump to: navigation, search
(→‎Repository)
(→‎Single File Inclusion)
 
(64 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
There are two ways to get a copy of µGFX: A [[#Stable_release|stable release]] and the latest version from the [[#Repository|git repository]]. We currently strongly recommend to use the git repository.
+
This article is a generic guide on how to get started with µGFX. It explains how a copy of the µGFX library can be obtained and where to begin reading the documentation in order to understand how the library is supposed to be used. There are a couple of other articles that explain how µGFX can be integrated into existing projects and how it can be used together with IDEs. You can find the list of these articles in the '''Using µGFX on...''' and '''Using IDEs''' sections on the [[Main_Page|main page]].
−
Before you start, please make sure that your application and the use of µGFX meets the [http://ugfx.org/license.html license] of this project.
+
−
We understand that integrating uGFX into your project might be the most difficult one for most users. Please do not hesitate to [[#Support|ask for help]] should you face any issues.
+
  
−
== Stable release ==
+
== Downloading ==
−
A copy of a stable release of µGFX can be downloaded from the [http://ugfx.org/downloads download section].
+
There are two ways to get a copy of µGFX: A [[#Stable_release|stable release]] and the latest version from the [[#Repository|git repository]]. We currently '''strongly''' recommend to use the git repository.
 +
Before you start, please make sure that your application and the use of µGFX meets the [http://ugfx.org/licensing license] of this project. Please [http://ugfx.org/about contact us] should you have any questions regarding licensing. If you're using µGFX for free please considering making a small [http://ugfx.org/download donation] to support our efforts.
  
−
== Repository ==
+
We understand that integrating µGFX into your project might be the most difficult part for most users. Please do not hesitate to [[#Support|ask for help]] should you face any issues.
 +
 
 +
=== Stable release ===
 +
A copy of a stable release of µGFX can be downloaded from the [https://community.ugfx.io/index.php?/files/ download section].
 +
 
 +
=== Repository ===
 
Please note that the following guide has been written for unix-like systems using the terminal. For Windows you may use a graphical git client such as [http://www.sourcetreeapp.com/ SourceTree].
 
Please note that the following guide has been written for unix-like systems using the terminal. For Windows you may use a graphical git client such as [http://www.sourcetreeapp.com/ SourceTree].
  
−
µGFX is developed through a git repository hosted at [http://bitbucket.org/Tectu/ugfx bitbucket.org].
+
µGFX is developed through a git repository hosted [https://git.ugfx.io/uGFX/uGFX here].
  
−
<pre>
+
<syntaxhighlight lang="bash">
 
cd /path/to/your/project/resources
 
cd /path/to/your/project/resources
−
git clone https://bitbucket.org/Tectu/ugfx ugfx
+
git clone https://git.ugfx.io/ugfx/ugfx.git ugfx
−
</pre>
+
</syntaxhighlight >
  
−
== Integrate µGFX ==
+
If you're more familiar with git you might want to read the following guide in order to learn how to seamlessly integrate the uGFX repository into your existing repository: [[Use_uGFX_repository_as_Git_Submodule]];
−
After you have successfully obtained a copy of µGFX, you have to include it into your current project. Note that µGFX internally uses Makefiles. You can find detailed descriptions for the currently supported platforms below. However, adding new platforms is fairly easy. See the GOS documentation to learn how.
+
  
−
BareBone (without OS)
+
== Architecture ==
−
ChibiOS/RT
+
Understanding the architecture of the µGFX library is rather important. See [[Architecture]].
−
FreeRTOS
+
−
Linux
+
−
Mac OS X
+
−
Win32
+
−
+
  
−
== Board files ==
+
'''Important:''' When you want to build a classic GUI with widgets like pushbuttons, sliders, dialog boxes and so on, use the [[GWIN]] module directly. There is no need to manually draw something or manually read out the touchscreen. Everything is handled automatically in the [[GWIN]] module.
−
Certain modules of µGFX such as the display and touchscreen drivers require a file which builds the interface to your actual hardware. This might sound scary but all the template and example files that come with µGFX make this job very easy.
+
  
−
You need the following two files in your project directory:
+
== Integrate uGFX ==
 +
After you have successfully obtained a copy of µGFX, you have to include it into your current project. The follow section will describe how uGFX can be integrated into an existing Makefile project or how it can be easily used with an IDE.
  
−
board_DRIVER.h
+
=== Makefiles ===
−
ginput_lld_mouse_board.h  (only required when you use a touchscreen)
+
The uGFX library comes with a built-in Makefile system (which is not mandatory to be used, see [[#Single_File_Inclusion|Single File Inclusion]] below). If your IDE / Project allows to use external, existing Makefiles, we highly recommend using this method of adding uGFX to your project.
−
If you're using some well known dev board, it's very likely that there are already board files for this board. Inside the /boards/base/ directory, you can find the supported boards. Simply include the board.mk for the appropriate board in your Makefile.
+
  
−
Otherwise, create a new directory inside /boards/base/ and copy the *_template.h which you can find in each drivers directory to it and rename them as shown above. Then implement the empty routines you can find inside that file. Note that not all the function implementations are required for the drivers to work. For example the GDISP module can work without an implementation to control the backlight. Just leave it empty in such cases.
+
Step-by-Step guide:
 +
# Set the '''GFXLIB''' variable to the path pointing to the µGFX library root directory
 +
# Include the main µGFX Makefile ''(/ugfx/gfx.mk)''
 +
# Add '''GFXSRC''' to the sources variable/list
 +
# Add '''GFXINC''' to the include paths variable/list
 +
# Include additional Makefiles of the µGFX library to include board files, drivers, ...
  
−
== Move on ==
+
=== Single File Inclusion ===
−
You can now move on by read the documentation of the different modules. Please note that you have to create gfxconf.h file in your project directory. In this file, you will have to enable each submodule of µGFX you want to use. You can find an example of a gfxconf.h file in the toplevel directory of uGFX showing all the available options. You can simply copy this file to your project's directory and rename it accordingly.
+
If your IDE or project doesn't allow using Makefiles there's another very easy way to include the uGFX library in your project. All that needs to be done is adding the ''/src/gfx_mk.c'' file to the sources and adding the µGFX library root directory to the compiler include path.
  
−
You may want to consider using the Linux, OS-X or the Win32 port of µGFX to develop your application on your host computer. This both simplifies and speeds up the process fo development a lot.  
+
Step-by-Step guide:
 +
# Add ''/src/gfx_mk.c'' to the sources in the files tree of your project
 +
# Add the path to the µGFX library root directory to the compiler include path
 +
# Add the source and header files of each driver that you want to be using the same way
 +
 
 +
'''''Note:''' Some features such as multiple-display support and pixmaps are currently not supported when using the single-file-inclusion method. µGFX v3.0 no longer has this limitation.''
 +
 
 +
=== Examples ===
 +
You can find a variety of different guides explaining how to integrate uGFX into an existing project on the [[Main_Page|main page]].
 +
 
 +
== Board files ==
 +
Certain modules of µGFX such as the display and touchscreen drivers require a file which builds the interface to your actual hardware. This board file tells µGFX how to talk to your hardware.<br/>
 +
The documentation of every module shows how to create these board files.<br/>See [[Board_File|board file]].
 +
 
 +
== Configuration ==
 +
The entire [[Configuration|configuration]] of µGFX happens in a file called '''gfxconf.h''' which you have to create. A template that can be copied can be found in '''/gfxconf.example.h'''. The configuration is crucial so please make sure that you at least scrolled once through the [[Configuration|configuration]] article.
 +
 
 +
== Demos ==
 +
The '''/demos''' directory contains a variety of different demos, reaching from single feature (per module sorted) demos up to complete application demos. These demos can be compiled easily by adding the corresponding '''demo.mk''' file to your Makefile. For example:
 +
<syntaxhighlight lang=make>include $(GFXLIB)/demos/modules/gwin/widgets/demo.mk</syntaxhighlight>
 +
'''''Note''': When including a demo Makefile, you have to make sure that you don't compile any other sources with it (eg. exclude your own main.c form the compilation process).''
  
 
== Support ==
 
== Support ==
 
There are two ways to get support for your µGFX related problems:
 
There are two ways to get support for your µGFX related problems:
 +
* Free public support by the community through the [http://forum.ugfx.org discussion forum]
 +
* A support agreement / contract
 +
Please do not hesitate to [http://ugfx.org/about contact us] if you're interested in a support agreement.
 +
  
−
Free public support by the community through the discussion forum
+
[[Category:General]]
−
A support agreement / contract
+
−
Please do not hesitate to contact us if you're interested into a support agreement.
+

Latest revision as of 16:45, 29 July 2021

This article is a generic guide on how to get started with µGFX. It explains how a copy of the µGFX library can be obtained and where to begin reading the documentation in order to understand how the library is supposed to be used. There are a couple of other articles that explain how µGFX can be integrated into existing projects and how it can be used together with IDEs. You can find the list of these articles in the Using µGFX on... and Using IDEs sections on the main page.

Downloading

There are two ways to get a copy of µGFX: A stable release and the latest version from the git repository. We currently strongly recommend to use the git repository. Before you start, please make sure that your application and the use of µGFX meets the license of this project. Please contact us should you have any questions regarding licensing. If you're using µGFX for free please considering making a small donation to support our efforts.

We understand that integrating µGFX into your project might be the most difficult part for most users. Please do not hesitate to ask for help should you face any issues.

Stable release

A copy of a stable release of µGFX can be downloaded from the download section.

Repository

Please note that the following guide has been written for unix-like systems using the terminal. For Windows you may use a graphical git client such as SourceTree.

µGFX is developed through a git repository hosted here. 

cd /path/to/your/project/resources
git clone https://git.ugfx.io/ugfx/ugfx.git ugfx

If you're more familiar with git you might want to read the following guide in order to learn how to seamlessly integrate the uGFX repository into your existing repository: Use_uGFX_repository_as_Git_Submodule;

Architecture

Understanding the architecture of the µGFX library is rather important. See Architecture.

Important: When you want to build a classic GUI with widgets like pushbuttons, sliders, dialog boxes and so on, use the GWIN module directly. There is no need to manually draw something or manually read out the touchscreen. Everything is handled automatically in the GWIN module.

Integrate uGFX

After you have successfully obtained a copy of µGFX, you have to include it into your current project. The follow section will describe how uGFX can be integrated into an existing Makefile project or how it can be easily used with an IDE.

Makefiles

The uGFX library comes with a built-in Makefile system (which is not mandatory to be used, see Single File Inclusion below). If your IDE / Project allows to use external, existing Makefiles, we highly recommend using this method of adding uGFX to your project.

Step-by-Step guide:

  1. Set the GFXLIB variable to the path pointing to the µGFX library root directory
  2. Include the main µGFX Makefile (/ugfx/gfx.mk)
  3. Add GFXSRC to the sources variable/list
  4. Add GFXINC to the include paths variable/list
  5. Include additional Makefiles of the µGFX library to include board files, drivers, ...

Single File Inclusion

If your IDE or project doesn't allow using Makefiles there's another very easy way to include the uGFX library in your project. All that needs to be done is adding the /src/gfx_mk.c file to the sources and adding the µGFX library root directory to the compiler include path.

Step-by-Step guide:

  1. Add /src/gfx_mk.c to the sources in the files tree of your project
  2. Add the path to the µGFX library root directory to the compiler include path
  3. Add the source and header files of each driver that you want to be using the same way

Note: Some features such as multiple-display support and pixmaps are currently not supported when using the single-file-inclusion method. µGFX v3.0 no longer has this limitation.

Examples

You can find a variety of different guides explaining how to integrate uGFX into an existing project on the main page.

Board files

Certain modules of µGFX such as the display and touchscreen drivers require a file which builds the interface to your actual hardware. This board file tells µGFX how to talk to your hardware.
The documentation of every module shows how to create these board files.
See board file.

Configuration

The entire configuration of µGFX happens in a file called gfxconf.h which you have to create. A template that can be copied can be found in /gfxconf.example.h. The configuration is crucial so please make sure that you at least scrolled once through the configuration article.

Demos

The /demos directory contains a variety of different demos, reaching from single feature (per module sorted) demos up to complete application demos. These demos can be compiled easily by adding the corresponding demo.mk file to your Makefile. For example: 

include $(GFXLIB)/demos/modules/gwin/widgets/demo.mk

Note: When including a demo Makefile, you have to make sure that you don't compile any other sources with it (eg. exclude your own main.c form the compilation process).

Support

There are two ways to get support for your µGFX related problems:

  • Free public support by the community through the discussion forum
  • A support agreement / contract

Please do not hesitate to contact us if you're interested in a support agreement.

Retrieved from "https://wiki.ugfx.io/index.php?title=Getting_Started&oldid=1908"