B4J Library [B4X] [XUI] xGauges and xGaugesRect Classes and Libraries

klaus · Nov 2, 2018

The xGauges and xGaugesRect Class do also exist as a B4X libary.
The xGauges.b4xlib, xGaugesRect.b4xlib, xGauges.xml and the xGaugesRect.xml files are attached.
You need to copy the xGauges.b4xlib and / or the xGaugesRect.b4xlib files to the AdditionlLibraries\B4X folder!
Don’t copy the xGauges.xml nor the xGaugesRect.xml file to the AdditionalLibraries folder, copy them in another folder for all b4xlib xml files.
Example: AdditionlLibraries\B4XlibXMLFiles
The xGauges.xml and the xGaugesRect.xml file are for help purposes and are useful with the B4X Help Viewer or the B4XObjectBrowser.
The xGauges.xml and the xGaugesRect.xml file were generated with this tool: b4xlib - XML generation

Current versions:
xGauges.b4xlib Version 2.1
xGaugesRect.b4xlib Version 1.3

Having seen this thread fuel gauge, it challenged me and I wrote this CustomView xGauges Class.
It works on all three products: B4A, B4i and B4J.
The xGauges.bas and xGaugesRect files are located in the B4J project and shared, relative link, in B4A and B4i.
The code is exactly the same, one class file, for all three platforms.

Demo programs for all three platforms and for both libraries are added.
Tested on PC, Android Samsung S6 and iPhone 6.
The shadows in the rectangular gauges look better on the devices than on the animated gif.

EDIT: 2025.08.25 Version 2.1 / version 1.3
Amended height error reported HERE.
Only the xGauges.b4xlib and the xGauges.xml files have been changed

EDIT: 2025.06.09 Version 2.0 / version 1.3
Only the xGaugesRect customview has changed.
Added CursorValueChanged event
Added a third cursor
Added the CursorStep property

EDIT: 2024.07.04 Version 2.0 / version 1.2
Added Parent property
Amended problem with ReInitialize

EDIT: 2022.07.22 Version 1.9 / version 1.1
'Set the corner radius bigger than the border width when corner radius > 0. bug report HERE.

EDIT: 2021.08.22 Version 1.8
Added BorderWidth, BorderColor and CorenerRadius properties.
Added ScaleMidLimit2StartPerCent, ScaleMidLimit2SweepPerCent, ScaleMidLimit2Color properties.
Added gradient colors for the limit zones.
Changed setValueMin and setValueMax from Int to Double.
Added new xGaugesRect library

EDIT: 2020.06.25 Version 1.7
Updated the Tag property according to Erels recommendation:
https://www.b4x.com/android/forum/t...lv-or-any-other-container.117992/#post-738358
Version 1.6
Added Click and LongClick events
Added BringToFront, SendToBack and asView methods

EDIT: 2019.03.12 Version 1.5
Amended cScaleMidLimitColor initialize value from 526 to 255
Amended setScaleColor missing reinitialize call routine
Amended Rotate Needle equation correction
Improved scale custom angles management
Added cCustomScaleMinAngle and cCustomScaleMaxAngle variables
Added NeedleON property shows or hides the needle

Version 1.4
Amended NeedleBitmapFileName designation in custom properties
Amended NeedleBitmapFileName set in the code for a Gaige added in the Designer
Amended custom angles problems.
Added RemoveView and ReInitialize methods

EDIT: 2018.12.20 Version 1.3
Amended problem reported in post#11.

EDIT: 2018.12.14 Version 1.2
Amended problem with GaugeTitle and GaugeUnit not updated in code.

xGauges

Author: Klaus CHRISTL
Version: 2.1

xGauges
- Functions:
  - AddToParent (Parent As Object, Left As Int, Top As Int, Width As Int) As String
    adds the xGauge to the Parent view.
    the parent object can be a B4XView or
    an Activity or a Panel in B4A, a Panel in B4i or a Pane in B4J
    there is no Height property, because the Height = Width
  - AsView As B4XView
    Returns the base panel of the gauge as B4XView
  - BringToFront
  - Initialize (Callback As Object, EventName As String) As String
    Initializes a xGauge
    Callback is the calling module
    EventNam3 is the generic event name, not used
  - IsInitialized As Boolean
    Tests whether the object has been initialized.
  - ReInitialize
    Reinitializes the gauge
  - RemoveView
    Removes the xGauge from its parent view
  - SendToBack
- Properties:
  - BackgroundColor As Int
    sets or gets the BackgroundColor
    it must be an xui.Color
    Example: xGauge1.BackgroundColor = xui.Color_White
  - BorderColor As Int
    sets or gets the BorderColor property
    it must be an xui.Color
    Example: xGauge1.BorderColor = xui.Color_Gray
  - BorderWidth As Int
    sets or gets the BorderWidth
    Example: xGauge1.BorderWidth = 5
  - CornerRadius As Int
    sets or gets the CornerRadius property
    Example: xGauge1.CornerRadius = 5
  - CustomScaleEndAngle As Int
    sets or gets the CustomScaleEndAngle
    Start angle for Custom scale angle gazge type.
    trigonometric angles 0 at 3 o'clock
    positive counter clockwise
  - CustomScaleStartAngle As Int
    sets or gets the CustomScaleStartAngle
    Start angle for Custom scale angle gazge type.
    trigonometric angles 0 at 3 o'clock
    positive counter clockwise
  - GaugeTitle As String
    sets or gets GaugeTitle property
  - GaugeType As String
    sets or gets GaugeType property
    possible values 90° Top, 180°, 270°, 90° Left, Custom scale angles
    for Custom scale angles you can set the start and the end angle
  - GaugeUnit As String
    sets or gets GaugeUnit property
  - HalfTicks As Boolean
    gets or sets if half (intermedaite) tick are required
    one tick between two main ticks
  - Left As Double
    sets or gets the Left property
  - MainTickNumber As Int
    gets or sets the number of main ticks
    for a scale from 0 to 10 then number must be 11
  - NeedleBitmapFileName As String
    sets or gets the NeedleBitmapFileName
    enter 'no file' without the quotes to use the default needle
  - NeedleColor As Int
    sets or gets the NeedleColor
    it must be an xui.Color
    Example: xGauge1.NeedleColor = xui.Color_Gray
  - NeedleON As Boolean
    sets or gets the NeedleON property
    shows or hides the needle
    default value True
  - Parent As B4XView
    gets the Parent view
    read only
  - ScaleColor As Int
    sets or gets the ScaleColor
    it must be an xui.Color
    Example: xGauge1.ScaleColor = xui.Color_Black
  - ScaleHighLimitColor As Int
    sets or gets the ScaleHighLimitColor
    it must be an xui.Color
    Example: xGauge1.ScaleHighLimitColor = xui.Color_Red
  - ScaleHighLimitPerCent As Double
    sets or gets the ScaleHighLimitPerCent property
    it is drawn from the given percent to the scale end
    given in pecent of the scale
  - ScaleLowLimitColor As Int
    sets or gets the ScaleLowLimitColor
    it must be an xui.Color
    Example: xGauge1.NeedleColor = xui.Color_RGB(526, 165, 0)
  - ScaleLowLimitPerCent As Double
    sets or gets the ScaleLowLimitPerCent property
    given in pecent of the scale
    it drawn from the scale start to the given percent
  - ScaleMidLimit2Color As Int
    sets or gets the ScaleMidLimit2Color
    it must be an xui.Color
    Example: xGauge1.ScaleMidLimitColor = xui.Color_RGB(526, 165, 0)
  - ScaleMidLimit2Colors As Int()
    sets or gets the ScaleMidLimit2Color
    it must be an Array of xui.Color
    Example: xGauge1.ScaleMidLimit2Color = Array As Int (xui.Color_RGB(255, 165, 0), xui.Color_Red)
  - ScaleMidLimit2StartPerCent As Double
    sets or gets the ScaleMidLimit2StartPerCent property
    it is drawn from the given start percent over the sweep percent
    given in pecent of the scale
  - ScaleMidLimit2SweepPerCent As Double
    sets or gets the ScaleMidLimit2SweepPerCent property
    it is drawn from the given start percent over the sweep percent
    given in pecent of the scale
  - ScaleMidLimitColor As Int
    sets or gets the ScaleMidLimitColor
    it must be an xui.Color
    Example: xGauge1.ScaleMidLimitColor = xui.Color_RGB(526, 165, 0)
  - ScaleMidLimitColors As Int
    sets or gets the ScaleMidLimitColors
    it must be an Array xui.Color
    Example: xGauge1.ScaleMidLimitColors = Array As Int (xui.Color_RGB(255, 165, 0), xui.Color_Red)
  - ScaleMidLimitStartPerCent As Double
    sets or gets the ScaleMidLimitStartPerCent property
    it is drawn from the given start percent over the sweep percent
    given in pecent of the scale
  - ScaleMidLimitSweepPerCent As Double
    sets or gets the ScaleMidLimitSweepPerCent property
    it is drawn from the given start percent over the sweep percent
    given in pecent of the scale
  - SmallTicksNumber As Int
    gets or sets the SmallTickNumber property
    SmallTicksNumber small ticks will drawn between two main ticks
    for a decimal scale SmallTickNumber = 10, eventhough only 9 ticks are seen, the 10th is hidden by the main tick
  - Tag As Object
  - TickText As String
    gets or sets the texts for the ticks
    the values between two || are displayed equally spaced on the scale
    Example: 0|20|40|60|80|100 or E|1/2|F
  - Top As Double
    sets or gets the Top property
  - Value As Double
    sets the value of the gauge
    the value must be between ValueMin and ValueMax
  - ValueMax As Double
    gets or sets the max value of the gauge
  - ValueMin As Double
    gets or sets the min value of the gauge
  - Width As Double
    sets or gets the width of the gauge
    there is no height property because the height is equal to the width

xGaugesRect only the specific Functions and Properties are shown below.

Author: Klaus CHRISTL
Version: 1.3

xGaugesRect
- Functions:
  - Cursor1Color As Int
    sets or gets the Cursor1Color property
    it must be an Array of xui.Color
  - Cursor1ON As Boolean
    sets or gets the Cursor1ON property
  - Cursor1Value As Double
    sets or gets the Corner1Value
    the value must be between ValueMin and ValueMax
  - Cursor2Color As Int
    sets or gets the Cursor2Color property
    it must be an Array of xui.Color
  - Cursor2ON As Boolean
    sets or gets the Cursor2ON property
  - Cursor2Value As Double
    sets or gets the Corner2Value
    the value must be between ValueMin and ValueMax
  - CursorColor As Int
    sets or gets the Cursor2Color property
    it must be an Array of xui.Color
  - CursorON As Boolean
    sets or gets the CursorON property
  - CursorValue As Double
    sets or gets the CornerValue
    the value must be between ValueMin and ValueMax
  - CursorStep As Double
    sets or gets the CursorStep property
    0 = no step

MikeCLX · Aug 17, 2021

Yes this looks awesome, I’ll give it a go in the morning and let you know.

MikeCLX · Aug 20, 2021

Works great,
only thing I did different in the 2nd mid scale I implemented was to call them ScaleMid2LimitColor etc instead of ScaleMidLimitColor2. As it made sense when I was doing it as it’s the second mid scale rather than a second color of the first one.

thanks for your great code and efforts it’s very helpful to be able to learn more about b4a from your examples

klaus · Aug 22, 2021

The xGauges library has been updated to version 1.8
Added new xGaugesRect library
Added BorderWidth, BorderColor and CorenerRadius properties.
Added ScaleMidLimit2StartPerCent, ScaleMidLimit2SweepPerCent, ScaleMidLimit2Color properties.
Added gradient colors for the limit zones.
Changed setValueMin and setValueMax from Int to Double.

klaus · Jul 12, 2022

The xGauges and xGaugesRect libraries have been updated to versions 1.9 and 1.1.
Set the corner radius bigger than the border width when corner radius > 0. bug report HERE.

klaus · Jul 4, 2024

The xGauges and xGaugesRect libraries have been updated to versions 2.0 and 1.2 in the first post.
Added Parent property
Amended problem with ReInitialize

sultan87 · May 12, 2025

Bonjour Klaus
je voudrais me servir de ces modules pour définir un thermomètre
j'ai chargé les différents modules du pavé 1
je développe en B4A
quand j'exécute je n'ai pas la totalité des exemples affiché dans le pavé 1

les gauges 'Consumption' 'Volt' 'rpm' ne sont pas affichées
est il possible d'utiliser 'Temp Oven' horizontal ou vertical en faisant bouger un curseur pour définir la température demandée avec un pas par exemple de 0.5 °C
Pierre

klaus · May 14, 2025

Comme l'écran des smartphones est petit, je n'ai pas affiché toutes les possibilités.

sultan87 said:
est il possible d'utiliser 'Temp Oven' horizontal ou vertical en faisant bouger un curseur pour définir la température demandée avec un pas par exemple de 0.5 °C

Oui, on peut déplacer les deux curseurs avec les doigts, mais leur pas n'est pas défini en interne.

Par-contre tu peux le faire en externe.
Ci-joint un programme démonstrateur.
Avec les boutons tu peux augmenter ou diminuer la valeur du curseur.
J'ai ajouté dans le module xGaugeRect un événement lorsqu'une valeur d'un curseur a changé.
Si tu déplaces le curseur avec un doigt, l'affichage de la valeur est mis à jour.
Dans cet événement, la valeur est arrondie à 0.5.

Testes cette version et si c'est OK je vais mettre à jour officiellement.

sultan87 · May 15, 2025

klaus said:
Comme l'écran des smartphones est petit, je n'ai pas affiché toutes les possibilités.

Oui, on peut déplacer les deux curseurs avec les doigts, mais leur pas n'est pas défini en interne.

Par-contre tu peux le faire en externe.
Ci-joint un programme démonstrateur.
Avec les boutons tu peux augmenter ou diminuer la valeur du curseur.
J'ai ajouté dans le module xGaugeRect un événement lorsqu'une valeur d'un curseur a changé.
Si tu déplaces le curseur avec un doigt, l'affichage de la valeur est mis à jour.
Dans cet événement, la valeur est arrondie à 0.5.

View attachment 164055

Testes cette version et si c'est OK je vais mettre à jour officiellement.

Bonsoir Klaus
Parfait
je voudrais modifier ValMin et ValMax dans le module Main sans toucher au module xGaugesRect
j'ai essayé
Private ValueMin As Double
Private ValueMax As Double
ValueMin = 0
ValueMax = 30
cela ne change rien les limites sont toujours 0 et 100
Pierre

klaus · May 15, 2025

Il serait plus facile de t'aider si tu mettais ton projet en annexe.
Pour modifier ces valeurs dans Main tu dois le faire comme ci-dessous:

B4X:

    Thermometre.ValueMin = 0
    Thermometre.ValueMax = 30
    Thermometre.HalfTicks = True
    Thermometre.MainTickNumber = 4
    Thermometre.TickText = "0|10|20|30"
    Thermometre.SmallTicksNumber = 10

Tu dois modifier ces valeurs avec le nom de xGauge qui est dans ton cas 'Thermometre'.
Donc ValMin et Val Max:

B4X:

    Thermometre.ValueMin = 0
    Thermometre.ValueMax = 30

Mais, tu dois aussi définir le nombre des marques principales de l'échelle et leur valeur.
Dans ton cas 0, 10, 20, 30, donc 4 et leur valeurs:

B4X:

   Thermometre.MainTickNumber = 4
    Thermometre.TickText = "0|10|20|30"

Et indiquer le nombre de petites marques de l'échelle entre deux marques principales.

B4X:

    Thermometre.SmallTicksNumber = 10

Et ça donnera ceci:

J'ai aussi mis

B4X:

    Thermometre.HalfTicks = True

pour être complet.
Ce n'est pas nécessaire si c'est déjà défini dans le Designer.

Y a-t-il une raison de vouloir changer ces valeurs dans le code et pas dans le Designer ?

sultan87 · May 15, 2025

klaus said:
Il serait plus facile de t'aider si tu mettais ton projet en annexe.
Pour modifier ces valeurs dans Main tu dois le faire comme ci-dessous:

B4X:

Thermometre.ValueMin = 0 Thermometre.ValueMax = 30 Thermometre.HalfTicks = True Thermometre.MainTickNumber = 4 Thermometre.TickText = "0|10|20|30" Thermometre.SmallTicksNumber = 10

Tu dois modifier ces valeurs avec le nom de xGauge qui est dans ton cas 'Thermometre'.
Donc ValMin et Val Max:

B4X:

Thermometre.ValueMin = 0 Thermometre.ValueMax = 30

Mais, tu dois aussi définir le nombre des marques principales de l'échelle et leur valeur.
Dans ton cas 0, 10, 20, 30, donc 4 et leur valeurs:

B4X:

Thermometre.MainTickNumber = 4 Thermometre.TickText = "0|10|20|30"

Et indiquer le nombre de petites marques de l'échelle entre deux marques principales.

B4X:

Thermometre.SmallTicksNumber = 10

Et ça donnera ceci:
View attachment 164107

J'ai aussi mis

B4X:

Thermometre.HalfTicks = True

pour être complet.
Ce n'est pas nécessaire si c'est déjà défini dans le Designer.

Y a-t-il une raison de vouloir changer ces valeurs dans le code et pas dans le Designer ?

Bonsoir Klaus
merci pour la réponse rapide
il n'y a aucune raison de vouloir modifier par ode
je n'avais pas vu que ces propriétés pouvaient être modifiées dans le Designer
je fais les modifs et je vous informe de mes tests
Bonne soirée
Pierre

sultan87 · May 20, 2025

Bonjour Klaus
je continue mes tests pour affichage d'un thermomètre

je voudrais mettre sur le cadran
de 0 à 18 couleur bleu
de 19 à 23 couleur verte
de 24 à 30 couleur rouge
serait il possible de faire les créneaux en fonction des valeurs plutôt qu'en pourcentage
Pierre

sultan87 · May 20, 2025

je me réponds
il faut laisser les pourcentages
tout dépend de ce que l'on veut
il suffit de faire des règles de trois
a quoi sert ScaleMidLimit2
peut on afficher un champ texte sous le paramètre GaugeUnit
Pierre

klaus · May 20, 2025

sultan87 said:
il suffit de faire des règles de trois

Eh oui.
Quand j'ai écrit cette bibliothèque je pensais que les les pourcentages était plus 'universels' que les valeurs.

sultan87 said:
a quoi sert ScaleMidLimit2

Il y a 4 zones.
Bas, LowLimit: de 0 et étendue x1%
Milieu bas, MidLimit: départ à x2% et étendue x3%
Milieu haut, MidLimti2: départ à x4% et étendue x5%
Haut, HighLimit: étendue x6% jusqu'à 100%.

sultan87 said:
peut on afficher un champ texte sous le paramètre GaugeUnit

Non.
Quel genre de texte penses-tu mettre ?

On peut modifier les couleur dans le code avec plusieurs couleurs dégradées :

B4X:

xGauge2.ScaleMidLimitColors = Array As Int(xui.Color_Green, xui.Color_Yellow)

sultan87 · May 20, 2025

merci Klaus
j'utilise xGauge3 donc afficher la valeur indiqué par l'aiguille dont je change la couleur en fonction de la valeur

klaus · May 20, 2025

Vu que tu avais parlé de xGaugesRect, j'étais resté sur des affichages rectangulaires.
Concernant les autres, je n'avais jamais pensé mettre encore la valeur numérique sur l'affichage car l'aiguille la montre déjà.
C'est comme les montres, à aiguilles ou à affichage digital.
Avec le variété d'affichages différents ce n'est pas facile de définir l'emplacement idéal pour l'affichage numérique.
Le seul, où ce serait possible est xGauge3.

sultan87 · May 20, 2025

merci Klaus
effectivement j'étais parti sur xGaugesRect mais je voulais vois ce qu'il était possible de faire avec xGauge3
sur xGaugesRect il y a la propriété CursorValue je ne retrouve pas cette propriété dans xGauge3
je voulais me servir pour modifier la couleur de l'aiguille en fonction de la valeur
Pierre

sultan87 · May 24, 2025

bonsoir Klaus
j'ai modifié ton projet pour afficher xGauge3
cela fonctionne correctement
ci-joint le projet
j'essaie de l'appliquer à mon projet
en changeant le valeur l'aiguille est toujours positionnée sur 0
je ne comprends pas
faut il obligatoirement utiliser B4XView
pouvez vous m'aider
Pierre

klaus · May 24, 2025

Il semble que ton projet est une projet B4XPages.
Il est préférable de zipper le project en cliquant sur la ligne ci dessous dans le module B4XMainPage, avec la touche Ctrl pressée.

sultan87 · May 24, 2025

Bonsoir Klaus
j'ai zipper mon projet (ci-joint)
parfois l'aiguille change de position en fonction de la température modifiée avec les touche + ou -
parfois elle ne bouge pas elle reste positionné sur 0
je ne comprends pas
pouvez vous m'aider
j'ai mis en commentaire les codes qui ne sont pas nécessaire pour l'exemple
merci d'avance
Pierre

sultan87 · May 24, 2025

Bonsoir Klaus
mon fichier .zip semble trop gros
comment faire pour que vous puissiez le voir
Pierre

B4J Library [B4X] [XUI] xGauges and xGaugesRect Classes and Libraries

Attachments

Member

Member

Expert

Expert

Expert

Active Member

Expert

Attachments

Active Member

Expert

Active Member

Active Member

Active Member

Expert

Active Member

Expert

Active Member

Active Member

Attachments

Expert

Active Member

Active Member

Privacy & Transparency

Privacy & Transparency