Spinner

  • Artikel

Der Spinner ist ein zusammengesetztes Steuerelement, das aus einer Inkrementschaltfläche, einer Dekrementschaltfläche und einem Bearbeitungssteuerelement besteht, die alle zum Bereitstellen von Dezimalwerten für die Anwendung verwendet werden.

Details

Der folgende Screenshot veranschaulicht den Menüband-Spinner.

Screenshot eines Spinnersteuerelements im Windows Live Moviemaker-Menüband.

Spinnereigenschaften

Das Menübandframework definiert eine Auflistung von Eigenschaftenschlüsseln für das Spinner-Steuerelement.

In der Regel wird eine Spinner-Eigenschaft auf der Menübandbenutzeroberfläche aktualisiert, indem der dem Steuerelement zugeordnete Befehl durch einen Aufruf der IUIFramework::InvalidateUICommand-Methode ungültig wird. Das Invaliditätsereignis wird von der IUICommandHandler::UpdateProperty-Rückrufmethode behandelt und die Eigenschaft aktualisiert.

Die IUICommandHandler::UpdateProperty-Rückrufmethode wird nicht ausgeführt, und die Anwendung wird nach einem aktualisierten Eigenschaftswert abgefragt, bis die Eigenschaft vom Framework erforderlich ist. Beispielsweise, wenn eine Registerkarte aktiviert ist und ein Steuerelement auf der Menüband-Benutzeroberfläche angezeigt wird, oder wenn eine QuickInfo angezeigt wird.

Hinweis

In einigen Fällen kann eine Eigenschaft über die IUIFramework::GetUICommandProperty-Methode abgerufen und mit der IUIFramework::SetUICommandProperty-Methode festgelegt werden.

In der folgenden Tabelle sind die Eigenschaftenschlüssel aufgeführt, die dem Spinner-Steuerelement zugeordnet sind.

Eigenschaftenschlüssel Hinweise
UI_PKEY_DecimalPlaces Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_DecimalValue Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty. Hinweis: Wenn der dem Steuerelement zugeordnete Befehl durch einen Aufruf von IUIFramework::InvalidateUICommand ungültig wird, fragt das Framework diese Eigenschaft ab, wenn UI_INVALIDATIONS_VALUE als Wert von Flags übergeben wird.
UI_PKEY_Enabled Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_FormatString Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_Increment Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_Keytip Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_Label Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_LargeHighContrastImage Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_LargeImage Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_MaxValue Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_MinValue Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_RepresentativeString Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_SmallHighContrastImage Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_SmallImage Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_TooltipDescription Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_TooltipTitle Kann nur durch ungültige Aktualisierung aktualisiert werden.

Im folgenden Codeabschnitt wird veranschaulicht, wie verschiedene Eigenschaften des Spinner-Steuerelements in der IUICommandHandler::UpdateProperty-Methode aktualisiert werden.

//
//  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;
}

Bemerkungen

Wenn der Mindestwert (UI_PKEY_MinValue) eines Spinners auf 0,0 initialisiert wird, sollte die Anwendung sicherstellen, dass jeder nachfolgende Wert, der vom Steuerelement bereitgestellt wird, nicht gleich -0,0 (negativer Nullwert) ist. Wenn der Spinner den Wert -0.0 bereitstellt, sollte die Anwendung diesen Wert mithilfe der IUIFramework::SetUICommandProperty-Methode auf 0.0 (positive Null) zurücksetzen, wie im folgenden Beispiel einer IUICommandHandler::Execute-Methode für ein Spinner-Steuerelement gezeigt.

Hinweis

Wenn dieser Test nicht ausgeführt wird und der Wert nicht korrigiert wird, zeigt das Bearbeitungsfeld des Steuerelements die Zeichenfolge "Auto" an.

//
//  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(&param);

        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;
}

Windows Ribbon Framework-Steuerelementbibliothek

Spinner-Markupelement