a plug-in with many properties

[Paul Forgey]

I'm writing a plug-in which has many properties, and some of these properties have a very specific (and lengthy) set of enumerated values. One in particular has almost 50 discrete textual values!



On the hardware side, do I correctly understand RegisterHardwareModuleProperty is strictly for the benefit of the module instance's global configuration only?



Why can't I do something similar in the device plug-in? Is it up to the user to know which properties my device plug-in will accept, and then what the valid range or values of those properties are?

[ScottBot]

On the hardware side, do I correctly understand RegisterHardwareModuleProperty is strictly for the benefit of the module instance's global configuration only?

I'm not sure if I understand the questions, but RegisterHardwareModuleProperty is the call that determines what properites are displayed for the Hardware Interface (it has nothing to do with Device properties). The property values are maintained per instance.

Why can't I do something similar in the device plug-in? Is it up to the user to know which properties my device plug-in will accept, and then what the valid range or values of those properties are?

You can create Properties and Values and also associate them together in your Device plugin as well. You can do this in your 'RegisterProperties' method like:

Code: Select all

// 
// Register the Property
if (!m_CallBackInfo.pHB_RegisterDeviceProperty( m_CallBackInfo.m_hModuleHandle, nDeviceNumber, "My Own Property", "Property 1", FALSE, "0", ioUnknown, TRUE, TRUE, TRUE, FALSE ))
{
    //
    // If the registration failed, this must be the first time, so create the property and values.
    if (!m_CallBackInfo.pHB_CreateDeviceProperty( "My Own Property", "Property 1", ptNumeric ))
        return( FALSE );

    if (!m_CallBackInfo.pHB_RegisterDeviceProperty( m_CallBackInfo.m_hModuleHandle, nDeviceNumber, "My Own Property", "Property 1", FALSE, "0", ioUnknown, TRUE, TRUE, TRUE, FALSE ))
        return( FALSE );

    //
    // Add Property Values
    m_CallBackInfo.pHB_CreateDevicePropertyValue( "My Own Property", "Value 1" );
    m_CallBackInfo.pHB_CreateDevicePropertyValue( "My Own Property", "Value 2" );
    m_CallBackInfo.pHB_CreateDevicePropertyValue( "My Own Property", "Value n" );
}

[Paul Forgey]

Code: Select all

    // 
    // If the registration failed, this must be the first time, so create the property and values. 
    if (!m_CallBackInfo.pHB_CreateDeviceProperty( "My Own Property", "Property 1", ptNumeric )) 
        return( FALSE ); 

ah ha! That's what I missed.



As for the hardware properties, I didn't ask my question very clearly, however you answered it. Thanks.

[Paul Forgey]

I created this helper function to save my fingers. I'm also posting it to make sure I understand a few basic points:



- if RegisterDeviceProperty fails, I need to call it again after creating the property

- I can add values to a ptList type with CreateDevicePropertyValue

- it's up to me to enforce ranges of integer types, unlike hardware properties which can set minimums and maximums

Code: Select all

BOOL RegisterProperty (DEVICE_MODULE_HANDLE module, 
                       int deviceNumber, 
                       const char *propertyName,
                       const char *propertyDescription,
                       BOOL defaultProperty,
                       const char *initialValue,
                       eIOType ioType,
                       BOOL persistent,
                       BOOL allowSameValueChange,
                       BOOL traceToDeviceLog,
                       BOOL dynamic,
                       ePropertyType type,
                       const char **enumList) // if ptList
{
    if (!g_CallBackInfo.pHB_RegisterDeviceProperty (g_CallBackInfo.m_hModuleHandle,
            deviceNumber, propertyName, propertyDescription, defaultProperty, initialValue,
            ioType, persistent, allowSameValueChange, traceToDeviceLog, dynamic))
    {
        if (!g_CallBackInfo.pHB_CreateDeviceProperty (propertyName, propertyDescription, type))
            return FALSE;
        
        if (enumList)
        {
            const char **ptr;
            for (ptr = enumList; *ptr; ++ptr)
                g_CallBackInfo.pHB_CreateDevicePropertyValue (propertyName, *ptr);
        }
        
        return g_CallBackInfo.pHB_RegisterDeviceProperty (g_CallBackInfo.m_hModuleHandle,
            deviceNumber, propertyName, propertyDescription, defaultProperty, initialValue,
            ioType, persistent, allowSameValueChange, traceToDeviceLog, dynamic);
    }
    return TRUE;
}

[ScottBot]

I created this helper function to save my fingers. I'm also posting it to make sure I understand a few basic points:

Every time I write this piece of code, I tell myself I should add it as a helper to the Device class....

- if RegisterDeviceProperty fails, I need to call it again after creating the property

Right. It could fail for other reasons (like you've already registered the same property), but it's usually because the property doesn't even exist in the system. Since it can't register it until it's created, you have to first create the Property and then register it (again).

- I can add values to a ptList type with CreateDevicePropertyValue

ptList is a type used for Hardware Interfaces, so you can't use CreateDevicePropertyValue with it. For Hardware Interfaces, you have to pass the list of valid property values in the RegisterHardwareModuleProperty call. If you mean ptAlphaList as the Device Property type, you might be in new territory with that. I've typically only used alpha lists for dynamic list generation, so I've never really assigned values with CreateDevicePropertyValue .

- it's up to me to enforce ranges of integer types, unlike hardware properties which can set minimums and maximums

Yes. The values that you can associate with the Property Value are really only 'suggested' values to help the user pick from common values. Although some parts of the UI restrict the user to just those values, there are many other ways that the value can be set to any value.