RangeData Manual

Table of Contents

• About
• Access
• Allocation/Deallocation
• Value
• Knots
• Ranges
• Color Modes
• RangePair
• Further Reading

About

The RangeData stores data on ranges and on the current value within these ranges. It is typically used with the LodObject. The RangeData class is defined in the customgui_range.h header file. The ID is CUSTOMDATATYPE_RANGE.

Access

RangeData data is typically accessed from a LodObject. See LodObject Manual.

  // This example reads the range data from the given LOD object.
 
  GeData rangeData;
  if (!lodObject->GetParameter(LOD_BAR, rangeData, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  CustomDataType* const customData = rangeData.GetCustomDataType(CUSTOMDATATYPE_RANGE);
  RangeData*      const rangeCustomData = static_cast<RangeData*>(customData);
 
  if (rangeCustomData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  const Float currentValue = rangeCustomData->GetCurrentValue();
  ApplicationOutput("Value: " + String::FloatToString(currentValue));

Allocation/Deallocation

RangeData objects are created with the usual tools, see Entity Creation and Destruction Manual (Classic).

• RangeData::Alloc(): Creates a new RangeData object.
• RangeData::Free(): Deletes the given RangeData object.

A RangeData object must be initialized:

• RangeData::Init(): Initializes the object with the passed range number.
• RangeData::Reset(): Resets the object to the initial state.

  // This example configures the given LOD object and defines the
  // number of manual groups using the RangeData data.
 
  // create custom data
  AutoAlloc<RangeData> rangeCustomData;
  if (rangeCustomData == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // configure LodObject
 
  lodObject->SetParameter(LOD_MODE, LOD_MODE_MANUAL_GROUPS, DESCFLAGS_SET::NONE);
  lodObject->SetParameter(LOD_CRITERIA, LOD_CRITERIA_SCREEN_H, DESCFLAGS_SET::NONE);
 
  // configure range data
  if (!rangeCustomData->Init(10))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // store to LodObject
 
  GeData rangeGeData;
  rangeGeData.SetCustomDataType(CUSTOMDATATYPE_RANGE, rangeCustomData);
  lodObject->SetParameter(LOD_BAR, rangeGeData, DESCFLAGS_SET::NONE);

Value

A RangeData stores a value between 0.0 and 1.0:

• RangeData::GetCurrentValue(): Returns the current value.
• RangeData::SetCurrentValue(): Sets the current value.

  // This example sets the current, user defined value of the range slider.
 
  // get range data
 
  GeData rangeData;
  lodObject->GetParameter(LOD_BAR, rangeData, DESCFLAGS_GET::NONE);
 
  CustomDataType* const customData = rangeData.GetCustomDataType(CUSTOMDATATYPE_RANGE);
  RangeData* const      rangeCustomData = static_cast<RangeData*>(customData);
  if (rangeCustomData == nullptr)
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  // User LOD Value
  lodObject->SetParameter(LOD_CRITERIA, LOD_CRITERIA_MANUAL_SLIDER, DESCFLAGS_SET::NONE);
 
  // set value
  rangeCustomData->SetCurrentValue(0.5);
  lodObject->SetParameter(LOD_BAR, rangeData, DESCFLAGS_SET::NONE);

Knots

Multiple knots can be added to a RangeData object. These knots define the borders of the ranges.

• RangeData::AddValue(): Adds a new knot at the given value. The existing range is split.
• RangeData::GetKnotsCount(): Returns the number of knots.
• RangeData::DeleteKnot(): Deletes the knot with the given index.
• RangeData::GetKnotValue(): Returns the value of the knot with the given index.
• RangeData::SetKnotValue(): Sets the value of the knot with the given index.
• RangeData::GetKnotIndexByValue(): Returns the index of the knot which value is equal to the given value.

  // This example clears the given RangeData and
  // adds two new knots.
 
  // clear
  rangeCustomData->Reset();
 
  // add knots
  rangeCustomData->AddValue(0.33);
  rangeCustomData->AddValue(0.66);
 
  // set selection
  rangeCustomData->SetSelectedKnot(0);
 

A single knot can be selected:

• RangeData::GetSelectedKnot(): Returns the index of the selected knot or NOTOK.
• RangeData::SetSelectedKnot(): Selects the knot with the given index.

  // This example deletes the currently selected knot.
 
  const Int knotIndex = rangeCustomData->GetSelectedKnot();
 
  rangeCustomData->DeleteKnot(knotIndex);

Ranges

Value ranges are defined as the space confined by knots:

• RangeData::GetRangesCount(): Returns the number of ranges.
• RangeData::GetRangeIndex(): Returns the range index for the given value.
• RangeData::GetSelectedRange(): Returns the index of the selected range or NOTOK.
• RangeData::SetSelectedRange(): Selects the range with the given index.

  // This example sets the color of the range containing the current value.
 
  // get current range
 
  const Float currentValue = rangeCustomData->GetCurrentValue();
  const Int   currentRange = rangeCustomData->GetRangeIndex(currentValue);
 
  // set color
 
  const Vector color { 1.0, 0.0, 0.0 };
  rangeCustomData->SetRangeColor(currentRange, color);

Color Modes

The ranges between knots can be colored in different ways:

• RangeData::IsPerRangeColorMode(): Returns true if a color is stored for each range.
• RangeData::SetColorMode(): Sets the color mode.
• RangeData::GetRangeColor(): Returns the color of the range with the given index.
• RangeData::SetRangeColor(): Sets the color of the range with the given index.
• RangeData::IsRandomColorMode(): Returns true if the assigned colors are random.
• RangeData::SetRandomColorMode(): Sets the random color mode.

  // This example assigns a new color to each range.
 
  // set mode
  rangeCustomData->SetRandomColorMode(false);
  rangeCustomData->SetColorMode(true);
 
  // get number of ranges
 
  const Int   rangeCount = rangeCustomData->GetRangesCount();
  const Float colorStep  = 1.0 / Float(rangeCount);
 
  // set color of each range
  for (Int i = 0; i < rangeCount; ++i)
  {
    const Vector hsv { Float(i) * colorStep, 1.0, 1.0 };
    const Vector rgb = HSVToRGB(hsv);
 
    rangeCustomData->SetRangeColor(i, rgb);
  }

RangePair

The dimensions of a range are stored with a RangePair object:

• RangeData::GetRange(): Returns the RangePair for the range with the given index.

The RangePair class includes:

• RangePair::Contains(): Returns true if the given value is within the range.
• RangePair::GetMin(): Return the minimal value of the range.
• RangePair::GetMax(): Returns the maximal value of the range.
• RangePair::GetCenter(): Returns the center of the range.

  // This example sets the current value to the center
  // of the current range.
 
  // get current value and range
 
  const Float currentValue = rangeCustomData->GetCurrentValue();
  const Int   currentRange = rangeCustomData->GetRangeIndex(currentValue);
 
  // get range center
 
  const RangePair rData = rangeCustomData->GetRange(currentRange);
  const Float     centerValue = rData.GetCenter();
 
  // set value
  rangeCustomData->SetCurrentValue(centerValue);

Further Reading

• LodObject Manual