SoftKey functions

Functions
EXTERN_C CCAUXDLL_API SOFTKEYHANDLE CCAUXDLL_CALLING_CONV	GetSoftKey (void)
EXTERN_C CCAUXDLL_API void CCAUXDLL_CALLING_CONV	SoftKey_release (SOFTKEYHANDLE)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getStatus (SOFTKEYHANDLE, uint16_t *value)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBacklightIntensity (SOFTKEYHANDLE, uint8_t key, uint8_t intensity)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getBacklightIntensity (SOFTKEYHANDLE, uint8_t key, uint8_t *intensity)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setMultipleBacklightIntensities (SOFTKEYHANDLE, uint8_t *keys, uint8_t *intensities, uint8_t array_size)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getMultipleBacklightIntensities (SOFTKEYHANDLE, uint8_t *keys, uint8_t *intensities, uint8_t array_size)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getBacklightSignal (SOFTKEYHANDLE, float64_t *frequency, uint8_t *dutyCycle)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getBacklightOnTime (SOFTKEYHANDLE, uint8_t *onTime)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getBacklightOffTime (SOFTKEYHANDLE, uint8_t *offTime)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getBacklightIdleTime (SOFTKEYHANDLE, uint8_t *idleTime)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getBacklightNrOfPulses (SOFTKEYHANDLE, uint8_t *nrOfPulses)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBacklightSignal (SOFTKEYHANDLE, float64_t frequency, uint8_t dutyCycle)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBacklightOnTime (SOFTKEYHANDLE, uint8_t onTime)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBacklightOffTime (SOFTKEYHANDLE, uint8_t offTime)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBacklightIdleTime (SOFTKEYHANDLE, uint8_t idleTime)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBacklightNrOfPulses (SOFTKEYHANDLE, uint8_t nrOfPulses)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBacklightOff (SOFTKEYHANDLE)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getBacklightEnabledDuringStartup (SOFTKEYHANDLE, CCStatus *status)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBacklightEnabledDuringStartup (SOFTKEYHANDLE, CCStatus status)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_getBootBacklightConfig (SOFTKEYHANDLE, uint8_t *bootIntensity, float32_t *bootFrequency, uint8_t *bootDutyCycle, uint8_t *postBootIntensity, float32_t *postBootFrequency, uint8_t *postBootDutyCycle, CCStatus *postBootConfig)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	SoftKey_setBootBacklightConfig (SOFTKEYHANDLE, uint8_t bootIntensity, float32_t bootFrequency, uint8_t bootDutyCycle, uint8_t postBootIntensity, float32_t postBootFrequency, uint8_t postBootDutyCycle, CCStatus postBootConfig)

Detailed Description

Functions in the SoftKey class

Function Documentation

GetSoftKey()

EXTERN_C CCAUXDLL_API SOFTKEYHANDLE CCAUXDLL_CALLING_CONV CrossControl::GetSoftKey

(

void

)

Factory function that creates instances of the SoftKey object.

Supported Platform(s): VI2

Returns

SOFTKEYHANDLE to an allocated SoftKey object. The returned handle needs to be deallocated using the SoftKey_release(SOFTKEYHANDLE) method when it's no longer needed.

Returns NULL if it fails to allocate memory.

Example Usage:

    SOFTKEYHANDLE pSoftKey = ::GetSoftKey();
    assert(pSoftKey);
 
    softkey_example(pSoftKey);
 
    SoftKey_release(pSoftKey);

SoftKey_getBacklightEnabledDuringStartup()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getBacklightEnabledDuringStartup	(	SOFTKEYHANDLE	,
		CCStatus *	status
	)

Is the Softkey Backlight enabled during startup? If enabled, the LED will blink to indicate startup progress. It will turn solid once the OS has started.

Supported Platform(s): VI2

Parameters

status

Softkey Backlight Enabled or Disabled during startup.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_getBacklightIdleTime()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getBacklightIdleTime	(	SOFTKEYHANDLE	,
		uint8_t *	idleTime
	)

Get SoftKey Backlight IDLE time.

Supported Platform(s): VI2

Parameters

idleTime

Time in 100ms increments.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_getBacklightIntensity()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getBacklightIntensity	(	SOFTKEYHANDLE	,
		uint8_t	key,
		uint8_t *	intensity
	)

Get softkey backlight intensity.

Supported Platform(s): VI2

Parameters

key	Key that's intensity is read. Start index 1.
intensity	Intensity value 0 - 100%

Due limitation in HW, readback value may differ from the value that was set.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    err = SoftKey_getBacklightIntensity(pSoftKey, 1, &value8);
    if (err == CrossControl::ERR_SUCCESS)
        cout << "SoftKey 1 backlight intensity is " << std::dec << value8 << std::endl;

SoftKey_getBacklightNrOfPulses()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getBacklightNrOfPulses	(	SOFTKEYHANDLE	,
		uint8_t *	nrOfPulses
	)

Get number of pulses during a Softkey backlight blink sequence.

Supported Platform(s): VI2

Parameters

nrOfPulses

Number of pulses.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_getBacklightOffTime()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getBacklightOffTime	(	SOFTKEYHANDLE	,
		uint8_t *	offTime
	)

Get SoftKey Backlight OFF time.

Supported Platform(s): VI2

Parameters

offTime

Time in 10ms increments.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_getBacklightOnTime()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getBacklightOnTime	(	SOFTKEYHANDLE	,
		uint8_t *	onTime
	)

Get SoftKey Backlight ON time.

Supported Platform(s): VI2

Parameters

onTime

Time in 10ms increments. 0 = off

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_getBacklightSignal()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getBacklightSignal	(	SOFTKEYHANDLE	,
		float64_t *	frequency,
		uint8_t *	dutyCycle
	)

Get SoftKey Backlight signal. Note, the values may vary from previously set values with setSignal. This is due to precision-loss in approximations.

Supported Platform(s): VI2

Parameters

frequency	Backlight blink frequency (0.2-50 Hz).
dutyCycle	Backlight on duty cycle (0-100%).

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    err = SoftKey_getBacklightSignal(pSoftKey, &fvalue64, &value8);
    cout.precision(1);
    if (err == CrossControl::ERR_SUCCESS)
        cout << "SoftKey backlight signal frequency is " << std::fixed << fvalue64 << " and duty cycle " << std::dec
             << value8 << std::endl;

SoftKey_getBootBacklightConfig()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getBootBacklightConfig	(	SOFTKEYHANDLE	,
		uint8_t *	bootIntensity,
		float32_t *	bootFrequency,
		uint8_t *	bootDutyCycle,
		uint8_t *	postBootIntensity,
		float32_t *	postBootFrequency,
		uint8_t *	postBootDutyCycle,
		CCStatus *	postBootConfig
	)

Get SoftKey backlight configuration during and after system boot. These settings applies to all SoftKeys, they cannot be configured individually. The behavior of the backlight LED in terms of intensity and blink frequency may be configured for system boot and after boot. The post-boot setting can also be disabled using the postBootConfig parameter. When disabled, the boot-settings will remain until a user application reconfigures the backlight.

Supported Platform(s): VI2

Parameters

bootIntensity	Backlight intensity (0-100%) during system boot.
bootFrequency	Backlight blink frequency (0.2-50 Hz) during system boot.
bootDutyCycle	Backlight on duty cycle (0-100%) during system boot.
postBootIntensity	Backlight intensity (0-100%) after system boot.
postBootFrequency	Backlight blink frequency (0.2-50 Hz) after system boot.
postBootDutyCycle	Backlight on duty cycle (0-100%) after system boot.
postBootConfig	Post-boot settings enabled or disabled.

Due limitation in HW, readback value may differ from the value that was set.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_getMultipleBacklightIntensities()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getMultipleBacklightIntensities	(	SOFTKEYHANDLE	,
		uint8_t *	keys,
		uint8_t *	intensities,
		uint8_t	array_size
	)

Get multiple SoftKey backlight intensities.

Supported Platform(s): VI2

Parameters

keys	Array of Keys that's intensity to set. Key indexing starts at number 1.
intensities	Array of intensities for the keys listed above. Inetnsity value in range 0 - 100%
array_size	Number of key/intensity - pairs

Due limitation in HW, readback value may differ from the value that was set.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    keys[0] = 1;
    keys[1] = 2;
    keys[2] = 3;
    keys[3] = 4;
    memset(intensities, 0, sizeof(intensities));
    err = SoftKey_getMultipleBacklightIntensities(pSoftKey, keys, intensities, sizeof(keys));
    if (err == CrossControl::ERR_SUCCESS)
    {
        cout << "SoftKey get multiple keys intensities" << std::endl;
        cout << "SoftKey 1 intensity: " << +intensities[0] << std::endl;
        cout << "SoftKey 2 intensity: " << +intensities[1] << std::endl;
        cout << "SoftKey 3 intensity: " << +intensities[2] << std::endl;
        cout << "SoftKey 4 intensity: " << +intensities[3] << std::endl;
    }

SoftKey_getStatus()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_getStatus	(	SOFTKEYHANDLE	,
		uint16_t *	value
	)

Get current status of keys

Supported Platform(s): VI2

Parameters

value

Bitfield of keys that are pressed. LSB is KEY1. Can be undefined if return value is error code.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    err = SoftKey_getStatus(pSoftKey, &value16);
    if (err == CrossControl::ERR_SUCCESS)
    {
        std::bitset<16> status(value16);
        cout << "SoftKey status " << status << std::endl;
    }

SoftKey_release()

EXTERN_C CCAUXDLL_API void CCAUXDLL_CALLING_CONV CrossControl::SoftKey_release

(

SOFTKEYHANDLE

)

Delete the SOFTKEY object.

Supported Platform(s): VI2

Returns

-

Example Usage:

    SOFTKEYHANDLE pSoftKey = ::GetSoftKey();
    assert(pSoftKey);
 
    softkey_example(pSoftKey);
 
    SoftKey_release(pSoftKey);

SoftKey_setBacklightEnabledDuringStartup()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBacklightEnabledDuringStartup	(	SOFTKEYHANDLE	,
		CCStatus	status
	)

Should the Softkey Backlight be enabled during startup? If enabled, the LED will blink to indicate startup progress. It will turn solid once the OS has started.

Supported Platform(s): VI2

Parameters

status

Enable or Disable the Softkey Backlight during startup.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_setBacklightIdleTime()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBacklightIdleTime	(	SOFTKEYHANDLE	,
		uint8_t	idleTime
	)

Set SoftKey Backlight IDLE time.

Supported Platform(s): VI2

Parameters

idleTime

Time in 100ms.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_setBacklightIntensity()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBacklightIntensity	(	SOFTKEYHANDLE	,
		uint8_t	key,
		uint8_t	intensity
	)

Set softkey backlight intensity.

Supported Platform(s): VI2

Parameters

key	Key that's intensity is set. Start index 1.
intensity	Intensity value in range 0 - 100%

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    err = SoftKey_setBacklightIntensity(pSoftKey, 1, 50);
    if (err == CrossControl::ERR_SUCCESS)
        cout << "SoftKey 1 backlight set to 50" << std::endl;

SoftKey_setBacklightNrOfPulses()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBacklightNrOfPulses	(	SOFTKEYHANDLE	,
		uint8_t	nrOfPulses
	)

Set number of pulses during a SoftKey Backlight blink sequence.

Supported Platform(s): VI2

Parameters

nrOfPulses

Number of pulses.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_setBacklightOff()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBacklightOff

(

SOFTKEYHANDLE

)

Set Softkey Backlight off.

Supported Platform(s): VI2

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_setBacklightOffTime()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBacklightOffTime	(	SOFTKEYHANDLE	,
		uint8_t	offTime
	)

Set SoftKey Backlight OFF time.

Supported Platform(s): VI2

Parameters

offTime

Time in 10ms increments.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    err = SoftKey_setBacklightOffTime(pSoftKey, 50);
    if (err == CrossControl::ERR_SUCCESS)
        cout << "SoftKey backlight OffTime set to 50" << std::endl;

SoftKey_setBacklightOnTime()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBacklightOnTime	(	SOFTKEYHANDLE	,
		uint8_t	onTime
	)

Set SoftKey Backlight ON time.

Supported Platform(s): VI2

Parameters

onTime

Time in 10ms increments. 0 = off

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    err = SoftKey_setBacklightOnTime(pSoftKey, 50);
    if (err == CrossControl::ERR_SUCCESS)
        cout << "SoftKey backlight OnTime set to 50" << std::endl;

SoftKey_setBacklightSignal()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBacklightSignal	(	SOFTKEYHANDLE	,
		float64_t	frequency,
		uint8_t	dutyCycle
	)

Set SoftKey Backlight signal.

Supported Platform(s): VI2

Parameters

frequency	SoftKey Backlight blink frequency (0.2-50 Hz).
dutyCycle	SoftKey Backlight ON duty cycle (0-100%).

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Note: The hardware cannot be set to have an on or off time of the LED that's longer than 2.55s (255*10ms) Hence there are limitations in this function when using frequencies slower than 0.39Hz. At 0.38Hz, the valid duty cycle range is [3 - 97]. At 0.30Hz, the valid duty cycle range is [24 - 76]. At 0.20Hz, the valid duty cycle range is [49 - 51]. At 0.19Hz and slower, the behavior is undefined for all duty cycles, so this is not allowed to be set. Additionally, the hardware cannot be set to have an on or off time of the LED that's shorter than 10ms. Hence, there are limitations in this function when using high frequencies. At 50 Hz, the valid duty cycle range is [50]. At 30 Hz, the valid duty cycle range is [30-70]. At 10 Hz, the valid duty cycle range is [10-90]. At 2 Hz, the valid duty cycle range is [2-98]. The behavior is undefined outside these ranges but setting 0% or 100% duty cycle will always work, regardless of the frequency. If you need to blink in an unsupported range, it can be done with a software timer instead.

Example Usage:

    err = SoftKey_setBacklightSignal(pSoftKey, 2, 50);
    if (err == CrossControl::ERR_SUCCESS)
        cout << "SoftKey backlight signal set to 2Hz 50% duty cycle" << std::endl;

SoftKey_setBootBacklightConfig()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setBootBacklightConfig	(	SOFTKEYHANDLE	,
		uint8_t	bootIntensity,
		float32_t	bootFrequency,
		uint8_t	bootDutyCycle,
		uint8_t	postBootIntensity,
		float32_t	postBootFrequency,
		uint8_t	postBootDutyCycle,
		CCStatus	postBootConfig
	)

Set SoftKey backlight configuration during and after system boot. These settings applies to all SoftKeys, they cannot be configured individually. The behavior of the backlight LED in terms of intensity and blink frequency may be configured for system boot and after boot. The post-boot setting can also be disabled using the postBootConfig parameter. When disabled, the boot-settings will remain until a user application reconfigures the backlight. Note that the frequency limitations mentioned in the description of SoftKey_setBacklightSignal also apply here.

Supported Platform(s): VI2

Parameters

bootIntensity	Backlight intensity (0-100%) during system boot.
bootFrequency	Backlight blink frequency (0.2-50 Hz) during system boot.
bootDutyCycle	Backlight on duty cycle (0-100%) during system boot.
postBootIntensity	Backlight intensity (0-100%) after system boot.
postBootFrequency	Backlight blink frequency (0.2-50 Hz) after system boot.
postBootDutyCycle	Backlight on duty cycle (0-100%) after system boot.
postBootConfig	Post-boot settings enabled or disabled.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

SoftKey_setMultipleBacklightIntensities()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::SoftKey_setMultipleBacklightIntensities	(	SOFTKEYHANDLE	,
		uint8_t *	keys,
		uint8_t *	intensities,
		uint8_t	array_size
	)

Set Multiple SoftKey backlight intensities.

Supported Platform(s): VI2

Parameters

keys	Array of Keys that's intensity to set. Key indexing starts at number 1.
intensities	Array of intensities for the keys listed above. Intensity value in range 0 - 100%
array_size	Number of key/intensity - pairs

To set all keys to same intensitity. Use key number 0 and array_size 1.

Not all values are supported on all platforms, ERR_NOT_SUPPORTED will indicate that.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    keys[0]        = 1;
    keys[1]        = 4;
    keys[2]        = 2;
    keys[3]        = 3;
    intensities[0] = 25;
    intensities[1] = 50;
    intensities[2] = 75;
    intensities[3] = 100;
    err            = SoftKey_setMultipleBacklightIntensities(pSoftKey, keys, intensities, sizeof(keys));
    if (err == CrossControl::ERR_SUCCESS)
    {
        cout << "SoftKey set multiple keys intensities" << std::endl;
        cout << "SoftKey 1 intensity: " << +intensities[0] << std::endl;
        cout << "SoftKey 2 intensity: " << +intensities[2] << std::endl;
        cout << "SoftKey 3 intensity: " << +intensities[3] << std::endl;
        cout << "SoftKey 4 intensity: " << +intensities[1] << std::endl;
    }