jdProperties

Tables & Data · jdashboardUI 24 · B4J / KeyValueStore

jdProperties es una clase ligera para guardar configuración y propiedades persistentes de una aplicación B4J. Internamente utiliza KeyValueStore, pero añade tres cosas importantes: caché en memoria, valores predeterminados y un texto de visualización opcional asociado a cada propiedad.

Es adecuada para preferencias de usuario, estado de la aplicación, opciones de interfaz, rutas recientes, valores de configuración y otros datos pequeños que deban sobrevivir entre ejecuciones.

Características destacadas

• Persistencia basada en KeyValueStore.
• Crea automáticamente la carpeta de almacenamiento dentro de File.DirApp.
• Caché en memoria para evitar lecturas repetidas.
• Valores predeterminados con SetDefaultValue.
• Valor real y texto visible separados con PutDisplayValueText.
• Comprobación de existencia con Exists.
• Eliminación individual o completa.
• Acceso opcional al KeyValueStore interno.
• Campo público isInitialized para comprobar el estado de inicialización.
• No utiliza Designer, Views ni eventos.

---

Dependencia

La librería jdashboardUI 24 declara la dependencia:

KeyValueStore

No necesitas crear un KeyValueStore manualmente para usar jdProperties.

---

Initialize

Declaración:

Private Properties As jdProperties

Inicialización típica:

Properties.Initialize("Settings", "settings.db")

Firma pública:

Initialize(FolderName As String, name As String)

En B4J, la clase:

1. crea File.DirApp/FolderName si no existe;
2. abre allí el archivo indicado por name;
3. inicializa la caché y el mapa de valores predeterminados;
4. establece isInitialized = True si todo termina correctamente.

Ejemplo:

Private Properties As jdProperties

Private Sub B4XPage_Created (Root1 As B4XView)
    Properties.Initialize("Settings", "settings.db")

    If Properties.isInitialized Then
        Log("Settings ready")
    End If
End Sub

Inicialización única

Si la instancia ya está inicializada, una nueva llamada a Initialize termina inmediatamente.

Por eso, para cambiar de archivo o carpeta, utiliza otra instancia de jdProperties.

---

Guardar y leer valores

Put

Guarda el valor en KeyValueStore y actualiza la caché:

Properties.Put("theme", "dark")
Properties.Put("window_width", 1280)
Properties.Put("remember_session", True)

Firma:

Put(k As String, v As Object)

Get

Lee primero desde la caché. Si la clave todavía no está en memoria, la obtiene desde KeyValueStore y después la almacena en la caché.

Dim Theme As String = Properties.Get("theme")
Dim Width As Int = Properties.Get("window_width")
Dim Remember As Boolean = Properties.Get("remember_session")

Firma:

Get(k As String) As Object

El retorno es Object, por lo que B4J realiza la conversión al tipo de destino cuando es compatible.

---

Valores predeterminados

Puedes registrar un valor predeterminado antes de leer una propiedad:

Properties.SetDefaultValue("theme", "dark")
Properties.SetDefaultValue("font_size", 14)
Properties.SetDefaultValue("show_toolbar", True)

Dim Theme As String = Properties.Get("theme")
Dim FontSize As Int = Properties.Get("font_size")
Dim ShowToolbar As Boolean = Properties.Get("show_toolbar")

Si la clave no existe en el almacenamiento, Get utiliza el valor configurado mediante SetDefaultValue.

SetDefaultValue

SetDefaultValue(k As String, defaultValue As Object)

GetDefaultValue

Dim DefaultTheme As Object = Properties.GetDefaultValue("theme")

Firma:

GetDefaultValue(k As String) As Object

Devuelve Null si no se configuró un valor predeterminado.

Los valores predeterminados se guardan únicamente en el Map interno de la instancia. No se escriben en el archivo settings.db.

---

Valor real + texto de visualización

jdProperties permite guardar un valor y, por separado, un texto descriptivo para mostrar al usuario.

Ejemplo:

Properties.Put("language", "es")
Properties.PutDisplayValueText("language", "Español")

Dim LanguageCode As String = Properties.Get("language")
Dim LanguageText As String = Properties.GetDisplayValueText("language")

Log(LanguageCode) ' es
Log(LanguageText) ' Español

Esto es útil para configuraciones donde guardas un ID, código o valor interno pero muestras un texto más amigable.

PutDisplayValueText

PutDisplayValueText(k As String, displayValueText As String)

Internamente se guarda con la clave:

k & "_DisplayValueText"

GetDisplayValueText

GetDisplayValueText(k As String) As String

Si no existe texto de visualización, devuelve una cadena vacía.

Conviene evitar crear manualmente claves que terminen en _DisplayValueText, porque ese sufijo está reservado por esta clase para el valor visible asociado.

---

Exists

Comprueba si una propiedad existe:

If Properties.Exists("theme") Then
    Log(Properties.Get("theme"))
Else
    Log("theme has not been saved")
End If

Firma:

Exists(k As String) As Boolean

La implementación revisa primero la caché y, si no encuentra la clave allí, consulta KeyValueStore.ContainsKey.

Orden recomendado

Cuando necesitas distinguir entre “no existe” y “existe”, comprueba primero Exists y luego llama a Get:

If Properties.Exists("server_url") Then
    Dim Url As String = Properties.Get("server_url")
End If

Esto evita depender de una clave que ya haya sido introducida en la caché por una lectura previa.

---

Remove

Elimina tanto el valor principal como su texto de visualización:

Properties.Remove("language")

Firma:

Remove(k As String)

También elimina ambas entradas de la caché.

---

DeleteAllProperties

Borra todas las propiedades persistidas y limpia la caché:

Properties.DeleteAllProperties

Firma:

DeleteAllProperties

Importante: la implementación no limpia el mapa de valores predeterminados. Después de DeleteAllProperties, un Get puede seguir devolviendo los defaults registrados con SetDefaultValue.

Ejemplo:

Properties.SetDefaultValue("theme", "dark")
Properties.Put("theme", "light")

Properties.DeleteAllProperties

Log(Properties.Get("theme")) ' dark

---

GetKeyValueStore

Permite obtener el objeto interno:

Dim Store As KeyValueStore = Properties.GetKeyValueStore

Firma:

GetKeyValueStore As KeyValueStore

Esto puede ser útil cuando necesitas una operación propia de KeyValueStore que jdProperties no expone.

Precaución con la caché

Si modificas el KeyValueStore directamente:

Dim Store As KeyValueStore = Properties.GetKeyValueStore
Store.Put("theme", "blue")

la caché interna de jdProperties no se actualiza automáticamente.

Si theme ya estaba en caché, una llamada posterior a:

Log(Properties.Get("theme"))

puede seguir devolviendo el valor anterior.

Para mantener la clase sincronizada, usa Put, Remove y DeleteAllProperties siempre que sea posible.

---

Ejemplo completo: preferencias de una aplicación

Sub Class_Globals
    Private Root As B4XView
    Private Properties As jdProperties
End Sub

Private Sub B4XPage_Created (Root1 As B4XView)
    Root = Root1

    Properties.Initialize("Settings", "settings.db")

    Properties.SetDefaultValue("theme", "dark")
    Properties.SetDefaultValue("language", "en")
    Properties.SetDefaultValue("autosave", True)

    LoadSettings
End Sub

Private Sub LoadSettings
    Dim Theme As String = Properties.Get("theme")
    Dim Language As String = Properties.Get("language")
    Dim AutoSave As Boolean = Properties.Get("autosave")

    Log("Theme: " & Theme)
    Log("Language: " & Language)
    Log("AutoSave: " & AutoSave)
End Sub

Private Sub SaveSettings
    Properties.Put("theme", "light")
    Properties.Put("language", "es")
    Properties.PutDisplayValueText("language", "Español")
    Properties.Put("autosave", False)
End Sub

Private Sub ResetSettings
    Properties.DeleteAllProperties
    LoadSettings
End Sub

---

Ejemplo: guardar selección por ID y descripción

Dim ProvinceId As Int = 13
Dim ProvinceName As String = "Manabí"

Properties.Put("province_id", ProvinceId)
Properties.PutDisplayValueText("province_id", ProvinceName)

Log(Properties.Get("province_id"))
Log(Properties.GetDisplayValueText("province_id"))

El valor persistido puede utilizarse internamente y el texto asociado puede mostrarse directamente en la interfaz.

---

Campo público

Campo	Tipo	Descripción
isInitialized	Boolean	True cuando Initialize terminó correctamente.

---

API pública completa

Miembro	Retorno	Descripción
Initialize(FolderName As String, name As String)	—	Inicializa carpeta, archivo, caché y defaults.
Get(k As String)	Object	Obtiene un valor usando caché y, si existe, default.
GetDisplayValueText(k As String)	String	Obtiene el texto visible asociado.
Put(k As String, v As Object)	—	Persiste un valor y actualiza la caché.
PutDisplayValueText(k As String, displayValueText As String)	—	Guarda el texto visible asociado.
Remove(k As String)	—	Elimina valor, texto visible y entradas de caché.
DeleteAllProperties	—	Borra todos los valores persistidos y la caché.
SetDefaultValue(k As String, defaultValue As Object)	—	Registra un default en memoria.
GetDefaultValue(k As String)	Object	Devuelve el default registrado o Null.
GetKeyValueStore	KeyValueStore	Devuelve el almacén interno.
Exists(k As String)	Boolean	Comprueba existencia en caché o almacenamiento.

---

Designer Properties y eventos

jdProperties es una clase de datos.

No declara:

• DesignerCreateView;
• AddToParent;
• Designer Properties;
• eventos públicos.

---

Notas del comportamiento real

• La librería analizada declara soporte para B4J.
• En B4J, FolderName se crea dentro de File.DirApp.
• Initialize captura internamente los errores de apertura y deja isInitialized = False si falla.
• La caché vive durante toda la vida de la instancia.
• Los defaults viven únicamente en memoria.
• DeleteAllProperties no elimina los defaults.
• El sufijo _DisplayValueText se utiliza internamente.
• El acceso directo mediante GetKeyValueStore puede dejar la caché desactualizada.

---

Relacionados

• JDataset: Data Binding y CRUD con SQLite.
• TableViewUtils: helpers visuales para tablas.
• JTableview: tabla visual avanzada.