NDEVR
API Documentation
UnitManager.h
1#pragma once
2#include "DLLInfo.h"
3#include <NDEVR/Unit.h>
4#include <NDEVR/SoftwareService.h>
5#include <NDEVR/Resource.h>
6#include <NDEVR/Pointer.h>
7#include <NDEVR/TranslatedString.h>
8#include <NDEVR/Dictionary.h>
9#include <NDEVR/INIInterface.h>
10namespace NDEVR
11{
12 class INIFactory;
17 class NDEVR_BASE_API UnitOption
18 {
19 public:
26 : name(name)
27 , id(id)
28 {}
29
32 virtual ~UnitOption() {};
37 virtual TranslatedString title() const { return name; };
42 virtual ConstPointer<Unit> unit() const = 0;
48 virtual bool hasMemberUnit(const ConstPointer<Unit>& unit) const = 0;
54 virtual ConstPointer<Unit> unit(const ConstPointer<Unit>&) const { return unit(); };
60
61
64 };
65
70 class NDEVR_BASE_API BasicUnitOption : public UnitOption
71 {
72 public:
83
87 virtual TranslatedString title() const final override;
93 virtual bool hasMemberUnit(const ConstPointer<Unit>& unit) const final override;
98 virtual ConstPointer<Unit> unit() const final override { return base_unit; };
103 virtual Buffer<ConstPointer<UnitOption>> subOptions() const final override { return m_sub_options; };
111 protected:
113 };
114
119 class NDEVR_BASE_API CoordinateUnitOption : public UnitOption
120 {
121 public:
130
134 virtual ConstPointer<Unit> unit() const final override;
140 virtual bool hasMemberUnit(const ConstPointer<Unit>& unit) const final override;
146 virtual ConstPointer<Unit> unit(const ConstPointer<Unit>& distance_unit) const final override;
147 };
148 class UnitManager;
154 class NDEVR_BASE_API CustomUnit
155 {
156 public:
168
171 virtual ~CustomUnit() {};
179 [[nodiscard]] virtual TranslatedString title() const { return name; };
185 [[nodiscard]] virtual Resource<ConstPointer<Unit>>& unitResource(UnitManager& manager) = 0;
191 [[nodiscard]] virtual Buffer<ConstPointer<UnitOption>> options( UnitManager& manager) const = 0;
196 virtual void prepareForINI(const UnitManager&) {};
201 virtual void setupINI(INIFactory&) = 0;
211 virtual void finishReadingINI( UnitManager&) {};
228 [[nodiscard]] virtual ConstPointer<Unit> defaultUnit( UnitManager&) const = 0;
229 };
230
235 class NDEVR_BASE_API ReferenceCustomUnit : public CustomUnit
236 {
237 public:
247
256 [[nodiscard]] virtual Resource<ConstPointer<Unit>>& unitResource(UnitManager& manager) override;
262 [[nodiscard]] virtual Buffer<ConstPointer<UnitOption>> options( UnitManager& manager) const override;
266 virtual void prepareForINI(const UnitManager&) override{}
270 virtual void setupINI(INIFactory&) override {};
275 virtual void resetToDefault( UnitManager&) override;
279 virtual void finishReadingINI( UnitManager&) override {};
285 virtual ConstPointer<Unit> currentUnit( UnitManager& manager) override;
291 [[nodiscard]] virtual ConstPointer<Unit> defaultUnit( UnitManager&) const override;
292 };
293
298 class NDEVR_BASE_API BasicCustomUnit : public CustomUnit
299 {
300 public:
312 virtual void prepareForINI(const UnitManager& manager) override;
317 virtual void setupINI(INIFactory& ini) override;
322 virtual void finishReadingINI(UnitManager& manager) override;
327 [[nodiscard]] virtual TranslatedString title() const override { return m_title; };
333 [[nodiscard]] virtual Resource<ConstPointer<Unit>>& unitResource(UnitManager& manager) override;
339 [[nodiscard]] Buffer<ConstPointer<UnitOption>> options(UnitManager& manager) const override;
345 [[nodiscard]] virtual ConstPointer<Unit> defaultUnit(UnitManager&) const override;
346 protected:
350 };
351
357 class NDEVR_BASE_API UnitManager : public INIInterface, public SoftwareServiceManager
358 {
359 public:
368 UnitManager(const UnitManager& manager);
377 void setToDefaultMetric(bool preserve_spacial);
382 void setToDefaultImperial(bool preserve_spacial);
387 void tieToManager(const UnitManager& manager);
392 void getINI(INIFactory& factory) override;
397 void prepareForINI(INIFactory& factory) override;
402 void finishReadingINI(INIFactory& factory) override;
412 [[nodiscard]] static UnitManager& DefaultManager();
413
419 [[nodiscard]] ConstPointer<Unit> unit(UnitCategory type) const;
484 [[nodiscard]] const Buffer<ConstPointer<UnitOption>>& areaUnitOptions() const { return m_area_unit_options; };
504 [[nodiscard]] const Buffer<DynamicPointer<CustomUnit>>& specialUnits() const { return m_special_units; }
527 bool hasSpecialUnit(const StringView& name) const;
561 [[nodiscard]] ConstPointer<Unit> unit(const StringView& name) const;
562
563
577 [[nodiscard]] ConstPointer<Unit> determineUnit(const Buffer<String>& unit_parts, UnitCategory type) const;
578
596 void addFormatOption(UnitCategory unit_type, const ConstPointer<UnitOption>& format_option);
602 void removeFormatOption(UnitCategory unit_type, const ConstPointer<UnitOption>& format_option);
616 public:
629 protected:
640 private:
641 //For INI read/writes
642 String angle_name;
643 String orientation_space_name;
644 String coordinate_space_name;
645 String distance_space_name;
646 String surface_area_name;
647 String volume_name;
648 String temperature_name;
649 String weight_name;
650 String lat_lon_name;
651 protected:
653 };
654}
TranslatedString m_title
The translated display title.
virtual void finishReadingINI(UnitManager &manager) override
Resolves the unit from the INI-stored name after reading INI data.
virtual ConstPointer< Unit > defaultUnit(UnitManager &) const override
Returns the default unit for this custom unit.
virtual void setupINI(INIFactory &ini) override
Registers this custom unit's settings with the given INI factory.
virtual void prepareForINI(const UnitManager &manager) override
Prepares internal state for INI serialization by capturing the current unit name.
virtual Resource< ConstPointer< Unit > > & unitResource(UnitManager &manager) override
Returns a mutable reference to the resource holding the current unit.
BasicCustomUnit(const StringView &id, const TranslatedString &title, UnitCategory type)
Constructs a BasicCustomUnit with the given identifier, title, and unit category.
String m_ini_unit_name
The unit name stored in INI for serialization.
Buffer< ConstPointer< UnitOption > > options(UnitManager &manager) const override
Returns the available unit options for this custom unit.
Resource< ConstPointer< Unit > > m_unit
The resource holding the current unit selection.
virtual TranslatedString title() const override
Returns the display title for this custom unit.
virtual Buffer< ConstPointer< UnitOption > > & editSubOptions()
Returns a mutable reference to the sub-options for editing.
BasicUnitOption(const ConstPointer< Unit > &unit, const TranslatedString &custom_title=TranslatedString())
Constructs a BasicUnitOption from a unit and an optional custom title.
Definition UnitManager.h:78
virtual TranslatedString title() const final override
Returns the display title, using the custom title if set.
TranslatedString custom_title
An optional custom display title.
Buffer< ConstPointer< UnitOption > > m_sub_options
Child sub-options within this unit option.
virtual ConstPointer< Unit > unit() const final override
Returns the base unit for this option.
Definition UnitManager.h:98
virtual Buffer< ConstPointer< UnitOption > > subOptions() const final override
Returns the sub-options for this unit option.
virtual bool hasMemberUnit(const ConstPointer< Unit > &unit) const final override
Checks whether the given unit matches this option or any sub-option.
ConstPointer< Unit > base_unit
The underlying unit this option wraps.
The equivelent of std::vector but with a bit more control.
Definition Buffer.hpp:58
Provides a constant, unmodifiable pointer that has shared ownership of a dynamically allocated object...
Definition Pointer.hpp:276
CoordinateUnitOption(const StringView &id, const TranslatedString &name)
Constructs a CoordinateUnitOption with the given identifier and name.
virtual ConstPointer< Unit > unit() const final override
Returns the coordinate unit.
virtual bool hasMemberUnit(const ConstPointer< Unit > &unit) const final override
Checks whether the given unit is a member of this coordinate option.
virtual TranslatedString title() const
Returns the translated display title.
virtual ConstPointer< Unit > currentUnit()
Returns the current unit without a manager context.
virtual void prepareForINI(const UnitManager &)
Prepares internal state for INI serialization.
String id
The unique string identifier of this custom unit.
virtual void finishReadingINI(UnitManager &)
Called after INI data has been read to finalize state.
virtual ~CustomUnit()
Virtual destructor.
CustomUnit(const StringView &id, const TranslatedString &name, UnitCategory unit_type)
Constructs a CustomUnit with the given identifier, name, and unit category.
UnitCategory unit_type
The category of unit this custom unit belongs to.
TranslatedString name
The translated display name of this custom unit.
virtual Buffer< ConstPointer< UnitOption > > options(UnitManager &manager) const =0
Returns the available unit options for this custom unit.
virtual void setupINI(INIFactory &)=0
Registers this custom unit's settings with the given INI factory.
virtual Resource< ConstPointer< Unit > > & unitResource(UnitManager &manager)=0
Returns a mutable reference to the resource holding the current unit.
virtual void resetToDefault(UnitManager &)
Resets this custom unit to its default value.
virtual ConstPointer< Unit > currentUnit(UnitManager &manager)
Returns the current unit using the given manager context.
virtual ConstPointer< Unit > defaultUnit(UnitManager &) const =0
Returns the default unit for this custom unit.
A hash-based key-value store, useful for quick associative lookups.
Definition Dictionary.h:64
Provides a modifiable pointer that has shared ownership of a dynamically allocated object.
Definition Pointer.hpp:356
Contains methods for easily reading and writing to an INI file including efficient casting,...
Definition INIReader.h:107
INIInterface()
Constructs an INIInterface with no default INI file.
virtual Buffer< ConstPointer< UnitOption > > options(UnitManager &manager) const override
Returns the available unit options from the referenced source.
virtual void prepareForINI(const UnitManager &) override
No-op for reference units since INI state is managed by the referenced source.
virtual void resetToDefault(UnitManager &) override
Resets this reference unit to its default value.
ReferenceCustomUnit(const StringView &id, const TranslatedString &name, UnitCategory unit_type)
Constructs a ReferenceCustomUnit with the given identifier, name, and unit category.
virtual void finishReadingINI(UnitManager &) override
No-op for reference units since INI state is managed by the referenced source.
virtual ConstPointer< Unit > defaultUnit(UnitManager &) const override
Returns the default unit from the referenced source.
virtual void setupINI(INIFactory &) override
No-op for reference units since INI state is managed by the referenced source.
virtual ConstPointer< Unit > currentUnit(UnitManager &manager) override
Returns the current unit from the referenced source.
virtual Resource< ConstPointer< Unit > > & unitResource(UnitManager &manager) override
Returns the unit resource from the referenced manager source.
virtual ~ReferenceCustomUnit()
Virtual destructor.
A class that can subscribe to any number of Resources which will get updates when the Resource(s) hav...
A core part of the engine, stores variables that can be listened to with ResourceListener which will ...
Definition Resource.h:42
Software Service Managers take a Software service to modify the behavior of the software.
The core String View class for the NDEVR API.
Definition StringView.h:58
The core String class for the NDEVR API.
Definition String.h:95
Any text displayed to the user should be defined as a TranslatedString which allows the program to lo...
Manages a collection of units across multiple data categories with INI persistence.
void prepareForINI(INIFactory &factory) override
Prepares internal state before INI serialization.
void tieToManager(const UnitManager &manager)
Ties this manager's units to mirror changes from another UnitManager.
Resource< ConstPointer< Unit > > distance_unit
Unit for describing non-dimensional distances.
Resource< ConstPointer< Unit > > surface_area_unit
Unit for describing surface areas.
ConstPointer< Unit > unit(const StringView &name) const
Looks up a unit by its string name.
Buffer< ConstPointer< UnitOption > > m_coordinate_format_options
All unit options for describing dimensional distances.
bool canBeImperial(const ConstPointer< Unit > &unit) const
Checks whether the given unit can be classified as imperial.
static ConstPointer< UnitOption > ActiveOption(const Buffer< ConstPointer< UnitOption > > &options, const ConstPointer< Unit > &unit)
Finds the active option matching the given unit from a buffer of options.
ConstPointer< Unit > specialUnit(const StringView &name)
Retrieves a special unit by name.
void addSpecialUnit(const DynamicPointer< CustomUnit > &custom_unit)
Adds a custom unit to this manager.
Buffer< ConstPointer< UnitOption > > m_lat_lon_unit_options
All unit options for describing position on the globe.
ConstPointer< Unit > determineUnit(const Buffer< String > &unit_parts, UnitCategory type) const
Determines a unit from a set of string parts and a category.
const Buffer< ConstPointer< UnitOption > > & latLonUnitOptions() const
Returns the available latitude/longitude unit options.
Buffer< ConstPointer< UnitOption > > m_area_unit_options
All unit options for describing surface areas.
const Buffer< ConstPointer< UnitOption > > & weightUnitOptions() const
Returns the available weight unit options.
void getINI(INIFactory &factory) override
Serializes or deserializes unit settings to/from an INI factory.
void setupDefaultLatLonOptions()
Populates the latitude/longitude unit options with default values.
Resource< ConstPointer< Unit > > volume_unit
Unit for describing volumes.
static UnitManager & DefaultManager()
Returns the singleton default UnitManager instance.
UnitManager(const UnitManager &manager)
Copy constructor.
const Buffer< DynamicPointer< CustomUnit > > & specialUnits() const
Returns all registered special (custom) units.
void setupDefaultVolumeOptions()
Populates the volume unit options with default values.
~UnitManager()
Destructor.
Resource< ConstPointer< Unit > > coordinate_space_unit
Unit for describing dimensional distances.
UnitManager & operator=(const UnitManager &manager)
Copy assignment operator.
ConstPointer< Unit > unit(UnitCategory type) const
Returns the currently selected unit for the given category.
Resource< ConstPointer< Unit > > & specialUnitResource(const StringView &name)
Retrieves the resource for a special unit by name.
void setupDefaultWeightOptions()
Populates the weight unit options with default values.
void clearUnitOptions(UnitCategory type)
Clears all unit options for the given category.
Resource< ConstPointer< Unit > > & unitResource(UnitCategory type)
Returns a mutable reference to the unit resource for the given category.
Buffer< ConstPointer< UnitOption > > m_distance_unit_options
All unit options for describing non-dimensional distances.
Buffer< ConstPointer< UnitOption > > m_weight_unit_options
All unit options for describing weights.
Resource< ConstPointer< Unit > > orientation_space_unit
Unit for describing dimensional angles.
Buffer< DynamicPointer< CustomUnit > > m_special_units
All registered special (custom) units.
void setToDefaultMetric(bool preserve_spacial)
Sets all units to default metric values.
void addFormatOption(UnitCategory unit_type, const ConstPointer< UnitOption > &format_option)
Adds a format option to the specified unit category.
ResourceListener * m_tie_to_listener
Listener used when this manager is tied to another manager.
static Resource< ConstPointer< Unit > > default_angle_unit
Default program-wide unit for describing non-dimensional angles.
void setUnitOptions(UnitCategory type, const Buffer< ConstPointer< UnitOption > > &options)
Sets the unit options for the given category from UnitOption objects.
void updateCoordinateBase(const ConstPointer< Unit > &base)
Updates the coordinate base unit and adjusts related coordinate options.
Buffer< ConstPointer< UnitOption > > m_volume_unit_options
All unit options for describing volumes.
void setUnitOptionsToDefault(UnitCategory type)
Resets unit options for the given category to their defaults.
UnitManager()
Default constructor.
Buffer< ConstPointer< UnitOption > > m_angle_unit_options
All unit options for describing non-dimensional angles.
const Buffer< ConstPointer< UnitOption > > & angleUnitOptions() const
Returns the available angle unit options.
const Buffer< ConstPointer< UnitOption > > & coordinateSpaceFormatOptions() const
Returns the available coordinate space format options.
void setToDefaultImperial(bool preserve_spacial)
Sets all units to default imperial values.
Buffer< ConstPointer< UnitOption > > unitOptions(UnitCategory units) const
Returns the unit options for the given category.
Dictionary< String, ConstPointer< UnitOption > > m_registered_units
Lookup of all registered unit options by name.
bool canBeMetric(const ConstPointer< Unit > &unit) const
Checks whether the given unit can be classified as metric.
Resource< ConstPointer< Unit > > lat_lon_unit
Unit for describing position on the globe.
void setUnit(UnitCategory type, const ConstPointer< Unit > &unit)
Sets the unit for the given category.
Resource< ConstPointer< Unit > > time_unit
Unit for describing time.
void setupDefaultAngleUnitOptions()
Populates the angle unit options with default values.
const Buffer< ConstPointer< UnitOption > > & distanceUnitOptions() const
Returns the available distance unit options.
void removeFormatOption(UnitCategory unit_type, const ConstPointer< UnitOption > &format_option)
Removes a format option from the specified unit category.
const Buffer< ConstPointer< UnitOption > > & volumeUnitOptions() const
Returns the available volume unit options.
Resource< ConstPointer< Unit > > angle_unit
Unit for describing non-dimensional angles.
void setupDefaultDistanceOptions()
Populates the distance unit options with default values.
void setupDefaultAreaOptions()
Populates the area unit options with default values.
void setUnitOptions(UnitCategory type, const Buffer< ConstPointer< Unit > > &options)
Sets the unit options for the given category from Unit objects.
const Buffer< ConstPointer< UnitOption > > & areaUnitOptions() const
Returns the available area unit options.
Resource< ConstPointer< Unit > > temperature_unit
Unit for describing temperature.
ConstPointer< Unit > orientationOffsetUnit() const
Returns the orientation offset unit used for orientation space.
bool hasSpecialUnit(const StringView &name) const
Checks whether a special unit with the given name exists.
static Resource< ConstPointer< Unit > > default_orientation_space_unit
Default program-wide unit for describing dimensional angles.
ConstPointer< Unit > parseUnit(const StringView &name, UnitCategory type=UnitCategory::e_undefined_unit) const
Parses a unit from a string name, optionally constrained to a category.
void finishReadingINI(INIFactory &factory) override
Finalizes unit state after reading INI data.
Resource< ConstPointer< Unit > > weight_unit
Unit for describing weights.
Dictionary< String, DynamicPointer< CustomUnit > > m_special_unit_lookup
Lookup of special units by name.
void setupDefaultCoordinateSpaceOptions()
Populates the coordinate space format options with default values.
String id
The unique string identifier of this unit option.
Definition UnitManager.h:63
UnitOption(const StringView &id, const TranslatedString &name)
Constructs a UnitOption with the given identifier and display name.
Definition UnitManager.h:25
virtual ConstPointer< Unit > unit() const =0
Returns the unit associated with this option.
virtual bool hasMemberUnit(const ConstPointer< Unit > &unit) const =0
Checks whether the given unit is a member of this option.
TranslatedString name
The translated display name of this unit option.
Definition UnitManager.h:62
virtual Buffer< ConstPointer< UnitOption > > subOptions() const
Returns the sub-options contained within this unit option.
Definition UnitManager.h:59
virtual TranslatedString title() const
Returns the translated display title for this unit option.
Definition UnitManager.h:37
virtual ConstPointer< Unit > unit(const ConstPointer< Unit > &) const
Returns a unit resolved relative to the given unit context.
Definition UnitManager.h:54
virtual ~UnitOption()
Virtual destructor.
Definition UnitManager.h:32
The primary namespace for the NDEVR SDK.
UnitCategory
A category of unit describing what it relates to.
Definition Unit.h:15
@ e_undefined_unit
No specific unit category assigned.
Definition Unit.h:16
Defines a unit of measurement for converting and displaying data values.
Definition Unit.h:39