Spinner

  • Articolo

Spinner è un controllo composito costituito da un pulsante di incremento, da un pulsante di decremento e da un controllo di modifica, tutti utilizzati per fornire valori decimali all'applicazione.

Dettagli

Lo screenshot seguente illustra lo spinner della barra multifunzione.

screenshot di un controllo di selezione nella barra multifunzione di Windows Live Moviemaker.

Proprietà della selezione

Il framework della barra multifunzione definisce una raccolta di chiavi di proprietà per il controllo Spinner.

In genere, una proprietà Spinner viene aggiornata nell'interfaccia utente della barra multifunzione invalidando il comando associato al controllo tramite una chiamata al metodo IUIFramework::InvalidateUICommand . L'evento di invalidazione viene gestito e le proprietà vengono aggiornate definite dal metodo di callback IUICommandHandler::UpdateProperty .

Il metodo di callback IUICommandHandler::UpdateProperty non viene eseguito e l'applicazione ha eseguito una query per un valore di proprietà aggiornato, fino a quando la proprietà non è richiesta dal framework. Ad esempio, quando viene attivata una scheda e viene visualizzato un controllo nell'interfaccia utente della barra multifunzione o quando viene visualizzata una descrizione comando.

Nota

In alcuni casi, una proprietà può essere recuperata tramite il metodo IUIFramework::GetUICommandProperty e impostata con il metodo IUIFramework::SetUICommandProperty .

Nella tabella seguente sono elencate le chiavi di proprietà associate al controllo Spinner.

Chiave proprietà Note
UI_PKEY_DecimalPlaces Può essere aggiornato solo tramite invalidazione.
UI_PKEY_DecimalValue Supporta IUIFramework::GetUICommandProperty e IUIFramework::SetUICommandProperty. Nota: Se il comando associato al controllo viene invalidato tramite una chiamata a IUIFramework::InvalidateUICommand, il framework esegue una query su questa proprietà quando UI_INVALIDATIONS_VALUE viene passato come valore di flag.
UI_PKEY_Enabled Supporta IUIFramework::GetUICommandProperty e IUIFramework::SetUICommandProperty.
UI_PKEY_FormatString Può essere aggiornato solo tramite invalidazione.
UI_PKEY_Increment Può essere aggiornato solo tramite invalidazione.
UI_PKEY_Keytip Può essere aggiornato solo tramite invalidazione.
UI_PKEY_Label Può essere aggiornato solo tramite invalidazione.
UI_PKEY_LargeHighContrastImage Può essere aggiornato solo tramite invalidazione.
UI_PKEY_LargeImage Può essere aggiornato solo tramite invalidazione.
UI_PKEY_MaxValue Può essere aggiornato solo tramite invalidazione.
UI_PKEY_MinValue Può essere aggiornato solo tramite invalidazione.
UI_PKEY_RepresentativeString Può essere aggiornato solo tramite invalidazione.
UI_PKEY_SmallHighContrastImage Può essere aggiornato solo tramite invalidazione.
UI_PKEY_SmallImage Può essere aggiornato solo tramite invalidazione.
UI_PKEY_TooltipDescription Può essere aggiornato solo tramite invalidazione.
UI_PKEY_TooltipTitle Può essere aggiornato solo tramite invalidazione.

La sezione seguente del codice illustra come vengono aggiornate varie proprietà del controllo Spinner nel metodo IUICommandHandler::UpdateProperty .

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

Commenti

Se il valore minimo (UI_PKEY_MinValue) di uno spinner viene inizializzato su 0,0, l'applicazione deve assicurarsi che qualsiasi valore successivo fornito dal controllo non sia uguale a -0,0 (zero negativo). Se spinner fornisce il valore -0.0, l'applicazione deve reimpostare questo valore su 0,0 (zero positivo) usando il metodo IUIFramework::SetUICommandProperty , come illustrato nell'esempio seguente di un metodo IUICommandHandler::Execute per un controllo Spinner.

Nota

Se questo test non viene eseguito e il valore lasciato non corretto, il campo di modifica del controllo visualizza la stringa "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(&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;
}

Libreria di controlli di Windows Ribbon Framework

Elemento di markup spinner