Difference between revisions of "GWIN"
(→A word on clipping) |
|||
| (22 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | The GWIN module takes usage of all the other modules and combines them into a complete GUI toolkit. Most commonly, the user will interact with the provided widgets through a [[GINPUT#Touchscreen|touchscreen]]. However, the [[GINPUT]] module | + | The GWIN module takes usage of all the other modules and combines them into a '''complete GUI toolkit'''. It provides everything from buttons and checkboxes over lists and even graph widgets and much more. Most commonly, the user will interact with the provided widgets through a [[GINPUT#Touchscreen|touchscreen]]. However, the [[GINPUT]] module also allows to use other input methods as well. |
There are three basic types of GWIN elements: | There are three basic types of GWIN elements: | ||
| − | |||
* [[Windows|Window]] | * [[Windows|Window]] | ||
* [[Widgets|Widget]] | * [[Widgets|Widget]] | ||
| Line 8: | Line 7: | ||
== API reference == | == API reference == | ||
| − | The API reference of the GWIN module can be found [http://ugfx.org | + | The API reference of the GWIN module can be found [http://api.ugfx.org/group___g_w_i_n.html here]. |
== GHandle == | == GHandle == | ||
| − | The | + | The <code>GHandle</code> data type is the main GWIN data type. All three GWIN types use this data type. The <code>GHandle</code> is the object reference and it is used to pass the different windows, widgets and containers around the different GWIN functions. In more technical terms: A <code>GHandle</code> is a reference to a GWIN element (widget, container, window, ...). |
| + | == Drawing == | ||
| + | All drawing operations that are provided by the [[Drawing|GDISP]] module can also be used within a GWIN [[Windows|window]]. | ||
| + | {| class="wikitable" | ||
| + | |- | ||
| + | ! GDISP !! GWIN | ||
| + | |- | ||
| + | | gdispDrawXxx(...) || gwinDrawXxx(...) | ||
| + | |- | ||
| + | | gdispFillXxx(...) || gwinFillXxx(GHandle gh, ...) | ||
| + | |} | ||
| + | All coordinates supplied to the GWIN drawing calls are relative to the specified window. The GWIN drawing support is usually used for two cases: | ||
| + | * Drawing/rendering routines for widgets | ||
| + | * To do custom drawing within the basic [[Windows|window]] element. | ||
| + | '''''Note:''' Unlike the GDISP drawing routines, the GWIN ones don't take a color parameter. Instead, the currently set foreground color is used.'' | ||
| + | == Redrawing mode == | ||
| + | It's possible to configure the redrawing behavior of GWIN. The redrawing mode defines how GWIN will handle redraw events. | ||
| + | |||
| + | '''''Note:''' Usually there is no need to change the default redrawing mode of GWIN. Only touch this if you know what you're doing.'' | ||
| + | |||
| + | === Normal mode === | ||
| + | Unless the default settings are overwritten by using any of the corresponding configuration settings (see below) in the [[configuration|configuration file]], GWIN will use the ''default redrawing mode''. | ||
| + | |||
| + | When a widget issues a redraw it will not be redrawn immediately to reduce stack usage. Instead, the GWIN logic will remember that it has to redraw the widget and will redraw it later on. GWIN uses a [[GTIMER]] timer to periodically redraw the pending widgets. However, as drawing operations are quite time intensive GWIN will automatically split up the redrawing jobs into individual redrawing operations. The GWIN redrawing routine will return in between these different redrawing jobs to allow other threads to become active. Therefore other threads can continue to work without extensive delay periods. | ||
| + | |||
| + | === Immediate mode === | ||
| + | In ''immediate redrawing mode'' GWIN will redraw a widget immediately when the widget wants to be redrawn. As this happens within the widget rendering routine this is a very stack intensive operation. | ||
| + | |||
| + | The ''immediate redrawing mode'' can be enabled through the [[configuration|configuration file]]: | ||
| + | <syntaxhighlight lang=c> | ||
| + | #define GWIN_REDRAW_IMMEDIATE TRUE | ||
| + | </syntaxhighlight> | ||
| + | |||
| + | === Single operation === | ||
| + | In ''single operation mode'' GWIN will no longer split up all pending redraws into individual jobs but perform all the pending drawing operations and return only after all of them are completed. It is discouraged to use this mode as it will keep other threads from executing any code for a long time. This is especially bad when it comes to threads which need to stream data, eg. when playing an audio file. | ||
| + | |||
| + | The ''single operation redrawing mode'' can be enabled through the [[configuration|configuration file]]: | ||
| + | <syntaxhighlight lang=c> | ||
| + | #define GWIN_REDRAW_SINGLEOP TRUE | ||
| + | </syntaxhighlight> | ||
[[Category:Module]] | [[Category:Module]] | ||
| + | |||
| + | == A word on clipping == | ||
| + | People often tend to use [[pixmaps]] to render things into off-screen memory and then blit the pixmap contents to the real display. One of the most reported "issues" is regarding the clipping area. The following paragraph tries to explain the clipping behavior of GWIN: | ||
| + | |||
| + | GWIN sets up a clipping area for its drawing but never resets it for efficiency. Effectively GWIN assumes that it has complete control over the display space and therefore the clipping rectangle. Trying to restore the clipping area after each operation would be slow. It would also require the existing clipping area to be saved which requires RAM and an API call that currently doesn’t exist. The solution is to manually set the clipping area before blitting the pixmap to the display. This is also allowable within the design of GWIN as GWIN will set it to what it wants before drawing again. | ||
Latest revision as of 09:17, 16 April 2018
The GWIN module takes usage of all the other modules and combines them into a complete GUI toolkit. It provides everything from buttons and checkboxes over lists and even graph widgets and much more. Most commonly, the user will interact with the provided widgets through a touchscreen. However, the GINPUT module also allows to use other input methods as well.
There are three basic types of GWIN elements:
Contents
API reference
The API reference of the GWIN module can be found here.
GHandle
The GHandle data type is the main GWIN data type. All three GWIN types use this data type. The GHandle is the object reference and it is used to pass the different windows, widgets and containers around the different GWIN functions. In more technical terms: A GHandle is a reference to a GWIN element (widget, container, window, ...).
Drawing
All drawing operations that are provided by the GDISP module can also be used within a GWIN window.
| GDISP | GWIN |
|---|---|
| gdispDrawXxx(...) | gwinDrawXxx(...) |
| gdispFillXxx(...) | gwinFillXxx(GHandle gh, ...) |
All coordinates supplied to the GWIN drawing calls are relative to the specified window. The GWIN drawing support is usually used for two cases:
- Drawing/rendering routines for widgets
- To do custom drawing within the basic window element.
Note: Unlike the GDISP drawing routines, the GWIN ones don't take a color parameter. Instead, the currently set foreground color is used.
Redrawing mode
It's possible to configure the redrawing behavior of GWIN. The redrawing mode defines how GWIN will handle redraw events.
Note: Usually there is no need to change the default redrawing mode of GWIN. Only touch this if you know what you're doing.
Normal mode
Unless the default settings are overwritten by using any of the corresponding configuration settings (see below) in the configuration file, GWIN will use the default redrawing mode.
When a widget issues a redraw it will not be redrawn immediately to reduce stack usage. Instead, the GWIN logic will remember that it has to redraw the widget and will redraw it later on. GWIN uses a GTIMER timer to periodically redraw the pending widgets. However, as drawing operations are quite time intensive GWIN will automatically split up the redrawing jobs into individual redrawing operations. The GWIN redrawing routine will return in between these different redrawing jobs to allow other threads to become active. Therefore other threads can continue to work without extensive delay periods.
Immediate mode
In immediate redrawing mode GWIN will redraw a widget immediately when the widget wants to be redrawn. As this happens within the widget rendering routine this is a very stack intensive operation.
The immediate redrawing mode can be enabled through the configuration file:
#define GWIN_REDRAW_IMMEDIATE TRUESingle operation
In single operation mode GWIN will no longer split up all pending redraws into individual jobs but perform all the pending drawing operations and return only after all of them are completed. It is discouraged to use this mode as it will keep other threads from executing any code for a long time. This is especially bad when it comes to threads which need to stream data, eg. when playing an audio file.
The single operation redrawing mode can be enabled through the configuration file:
#define GWIN_REDRAW_SINGLEOP TRUEA word on clipping
People often tend to use pixmaps to render things into off-screen memory and then blit the pixmap contents to the real display. One of the most reported "issues" is regarding the clipping area. The following paragraph tries to explain the clipping behavior of GWIN:
GWIN sets up a clipping area for its drawing but never resets it for efficiency. Effectively GWIN assumes that it has complete control over the display space and therefore the clipping rectangle. Trying to restore the clipping area after each operation would be slow. It would also require the existing clipping area to be saved which requires RAM and an API call that currently doesn’t exist. The solution is to manually set the clipping area before blitting the pixmap to the display. This is also allowable within the design of GWIN as GWIN will set it to what it wants before drawing again.
