title | description | ms.assetid | ms.topic | ms.date |
---|---|---|---|---|
Spinner |
The Spinner is a composite control that consists of an increment button, a decrement button, and an edit control, all of which are used to provide decimal values to the application. |
63689ed3-7326-4f7a-b700-d89e9b501ef1 |
article |
05/31/2018 |
The Spinner is a composite control that consists of an increment button, a decrement button, and an edit control, all of which are used to provide decimal values to the application.
The following screen shot illustrates the Ribbon Spinner.
The Ribbon framework defines a collection of property keys for the Spinner control.
Typically, a Spinner property is updated in the ribbon UI by invalidating the Command associated with the control through a call to the IUIFramework::InvalidateUICommand method. The invalidation event is handled, and the property updates defined, by the IUICommandHandler::UpdateProperty callback method.
The IUICommandHandler::UpdateProperty callback method is not executed, and the application queried for an updated property value, until the property is required by the framework. For example, when a tab is activated and a control revealed in the ribbon UI, or when a tooltip is displayed.
Note
In some cases, a property can be retrieved through the IUIFramework::GetUICommandProperty method and set with the IUIFramework::SetUICommandProperty method.
The following table lists the property keys that are associated with the Spinner control.
Property Key | Notes |
---|---|
UI_PKEY_DecimalPlaces | Can only be updated through invalidation. |
UI_PKEY_DecimalValue | Supports IUIFramework::GetUICommandProperty and IUIFramework::SetUICommandProperty. Note: If the Command associated with the control is invalidated through a call to IUIFramework::InvalidateUICommand, the framework queries this property when UI_INVALIDATIONS_VALUE is passed as the value of flags. |
UI_PKEY_Enabled | Supports IUIFramework::GetUICommandProperty and IUIFramework::SetUICommandProperty. |
UI_PKEY_FormatString | Can only be updated through invalidation. |
UI_PKEY_Increment | Can only be updated through invalidation. |
UI_PKEY_Keytip | Can only be updated through invalidation. |
UI_PKEY_Label | Can only be updated through invalidation. |
UI_PKEY_LargeHighContrastImage | Can only be updated through invalidation. |
UI_PKEY_LargeImage | Can only be updated through invalidation. |
UI_PKEY_MaxValue | Can only be updated through invalidation. |
UI_PKEY_MinValue | Can only be updated through invalidation. |
UI_PKEY_RepresentativeString | Can only be updated through invalidation. |
UI_PKEY_SmallHighContrastImage | Can only be updated through invalidation. |
UI_PKEY_SmallImage | Can only be updated through invalidation. |
UI_PKEY_TooltipDescription | Can only be updated through invalidation. |
UI_PKEY_TooltipTitle | Can only be updated through invalidation. |
The following section of code demonstrates how various properties of the Spinner control are updated in the IUICommandHandler::UpdateProperty method.
//
// FUNCTION: UpdateProperty()
//
// PURPOSE: Called by the Ribbon framework when a command property needs
// to be updated.
//
// COMMENTS: This function is used to provide new command property values for
// the spinner when requested by the Ribbon framework.
//
STDMETHODIMP CCommandHandler::UpdateProperty(
UINT nCmdID,
REFPROPERTYKEY key,
const PROPVARIANT* ppropvarCurrentValue,
PROPVARIANT* ppropvarNewValue)
{
UNREFERENCED_PARAMETER(ppropvarCurrentValue);
HRESULT hr = E_NOTIMPL;
if (nCmdID == IDR_CMD_SPINNER_RESIZE)
{
// Set the minimum value
if (IsEqualPropertyKey(key, UI_PKEY_MinValue))
{
ZeroMemory(ppropvarNewValue, sizeof(*ppropvarNewValue));
ppropvarNewValue->vt = VT_DECIMAL;
VarDecFromR8(-10.0, &ppropvarNewValue->decVal);
hr = S_OK;
}
// Set the maximum value
else if (IsEqualPropertyKey(key, UI_PKEY_MaxValue))
{
ZeroMemory(ppropvarNewValue, sizeof(*ppropvarNewValue));
ppropvarNewValue->vt = VT_DECIMAL;
VarDecFromR8(10.0, &ppropvarNewValue->decVal);
hr = S_OK;
}
// Set the increment
else if (IsEqualPropertyKey(key, UI_PKEY_Increment))
{
ZeroMemory(ppropvarNewValue, sizeof(*ppropvarNewValue));
ppropvarNewValue->vt = VT_DECIMAL;
VarDecFromR8(2.0, &ppropvarNewValue->decVal);
hr = S_OK;
}
// Set the number of decimal places
else if (IsEqualPropertyKey(key, UI_PKEY_DecimalPlaces))
{
hr = InitPropVariantFromUInt32(1, ppropvarNewValue);
hr = S_OK;
}
// Set the format string
else if (IsEqualPropertyKey(key, UI_PKEY_FormatString))
{
hr = InitPropVariantFromString(L"px", ppropvarNewValue);
hr = S_OK;
}
// Set the representative string
else if (IsEqualPropertyKey(key, UI_PKEY_RepresentativeString))
{
hr = InitPropVariantFromString(L"AAAAAAA", ppropvarNewValue);
hr = S_OK;
}
}
return hr;
}
If the minimum value (UI_PKEY_MinValue) of a Spinner is initialized to 0.0, the application should ensure that any subsequent value supplied by the control does not equal -0.0 (negative zero). If the Spinner supplies a value of -0.0, the application should reset this value to 0.0 (positive zero) using the IUIFramework::SetUICommandProperty method as shown in the following example of an IUICommandHandler::Execute method for a Spinner control.
Note
If this test is not performed and the value left uncorrected, the edit field of the control displays the string "Auto".
//
// FUNCTION: Execute()
//
// PURPOSE: Called by the Ribbon framework when a command is executed by the user.
// For this sample, when an increment or decrement button is pressed or
// a new value is entered in the Spinner edit field.
//
STDMETHODIMP CCommandHandler::Execute(
UINT nCmdID,
UI_EXECUTIONVERB verb,
const PROPERTYKEY* key,
const PROPVARIANT* ppropvarValue,
IUISimplePropertySet* pCommandExecutionProperties)
{
UNREFERENCED_PARAMETER(pCommandExecutionProperties);
HRESULT hr = E_NOTIMPL;
if (verb == UI_EXECUTIONVERB_EXECUTE)
{
RenderParam param;
g_renderer.GetRenderParam(¶m);
if (nCmdID == IDR_CMD_SPINNER_RESIZE)
{
// Spinner value is negative.
if (!(ppropvarValue->decVal.sign == 0))
{
// Check if the value supplied by the Spinner is -0
// and correct the value if necessary.
// If this value is left uncorrected, the edit field
// of the control will display the string "Auto" when
// UI_PKEY_MinValue is set to 0.
if (ppropvarValue->decVal.Lo64 == 0)
{
// Initialize a new PROPVARIANT structure.
PROPVARIANT m_varNewVal;
PropVariantInit(&m_varNewVal);
// The replacement DECIMAL value.
DECIMAL m_dVal;
hr = VarDecFromI4(0, &m_dVal);
if (FAILED(hr))
{
return hr;
}
// Initialize the new DECIMAL value.
UIInitPropertyFromDecimal(UI_PKEY_DecimalValue, m_dVal, &m_varNewVal);
// Set the UI_PKEY_DecimalValue to the new DECIMAL value.
hr = g_pFramework->SetUICommandProperty(nCmdID, UI_PKEY_DecimalValue, m_varNewVal);
if (FAILED(hr))
{
return hr;
}
}
// Decrease size of shape in document space.
param.iShapeSizeIncrement = -ppropvarValue->intVal;
}
// Spinner value is positive.
else
{
// Increase size of shape in document space.
param.iShapeSizeIncrement = ppropvarValue->intVal;
}
}
g_renderer.UpdateRenderParam(param);
}
return hr;
}