How to implement Progressive Disclosure in C++ API

Question

Following the article Programmers Are People Too by Ken Arnold, I have been trying to implement the progressive disclosure pattern for an API.

Basically, the idea mentioned in the text is to break the API into categories and only present the user with what he or she needs. The rest is hidden, reducing complexity for someone using the API. In the text, he presents his idea with the JButton class and its 100+ methods:

[...] we could use progressive disclosure to help reduce the complexity of that JButton class: put the expert stuff in an object returned by a getExpertKnobs() method, and the graphics subsystem hooks in an object returned by a getIntegrationHooks() method, and you would be left with a button API that had just a handful of methods—the basic methods we all need.

I have been trying to implement a minimal example of this using C++. So far, I have not gotten acceptable results. What I want is this behavior and simplicity:

First, the class containing only the basic and widely spread methods:

struct Base
{
    Base()
    {
        // Initialize attributes (possibly many)
    }

    void simpleMethod()
    {
        // Do something simple...
    }

    ExtBase ext() 
    {
        // Access to advanced features;
        // this is the tricky part for me...
    }

private:
    // Attributes...
};

Then, the class containing the advanced/expert stuff:

struct ExtBase
{
    ExtBase()
    {
        // Not sure of what goes here...
    }

    void advancedMethod()
    {
        // Do something complicated...
    }
};

Ideally, this "API" could be used simply like this by the user:

int main()

{
    Base aBase;

    aBase.simpleMethod();           // OK
    aBase.advancedMethod();         // Fails. Not available by default.

    aBase.ext().simpleMethod();     // Possibly OK, not sure...
    aBase.ext().advancedMethod();   // OK

    return 0;
}

I have been looking around the web to find examples of this, but so far, nothing really interesting came up. I did find an example in Java from this library but I was not able to replicate it in C++.

Does anyone have any idea on how this could be done?

Answer 1

The following is a code example that creates two "twin" objects where the lifetime is closely related to each other.

Technically, Extra is a member of Base, but Extra consists of nothing but a pointer (reference) to the instance of Base that contains it. Think of it as a child node that has a pointer to a parent node.

I have used this pattern with Visual C++ (in particular when programming in Component Object Model environments). However, I do not know whether this pattern is valid in C++ Standard.

I have heard that, in some C++ compiler environments, the taking and storing of the address of *this during constructor execution is illegal, which may in fact return different addresses during and after constructor execution.

Note that this pattern breaks several things: Base is not trivially-copyable, not trivially-moveable, and not trivially-assignable. If you need those things you have to explicitly implement these operations.

class Base
{
public:
    class Extra
    {
        friend class Base;

    public:
        // able to access Base members via m_refBase
        void extraMethod();

        // if Base is const-qualified, the Extra& that is 
        // returned from Base::extra() is also const-qualified,
        // therefore the const-qualified Extra::extraMethod() 
        // will be selected
        // (and non-const methods on Extra will not be callable) 
        void extraMethod() const;

    private:
        // constructor - to be called by Base constructor
        Extra(Base& refBase)
            : m_refBase(refBase)
        {
        }

    private:
        Base& m_refBase;
    };

    friend class Extra;

public:
    void baseMethod();

public:
    Extra& extra() { return m_extra; }
    const Extra& extra() const { return m_extra; }

public:
    Base()
        : m_someOtherData(...)
        , m_extra(*this)
    {
        m_someOtherData.otherInitializations();
    }

private:
    SomeOtherData m_someOtherData;
    Extra m_extra; 
};

Answer 2

This is fairly simple, all things considered. What you need to do is create a class (nested or not) which is a friend of the main one. It will be created on-demand when you access the "advanced" API. The overall code looks like this:

class Main
{
private:
    class Advanced
    {
    public:
        void AdvancedMethod() {/*directly access Main's internals*/}

    private:
        Advanced(Main &m) :data_(m) {}

        Main &data_;

        friend class Main;
    };

    friend class Advanced;
public:

    Advanced Adv() {return Advanced(*this);}
};

Note that we construct a new Advanced every time you call Adv. We could have it be a member variable, but this permits us to:

• Not disturb the size/layout of Main. Advanced takes up some space, so by adding it as a member variable of Main, we make Main take up more space.
• Not disturb the functionality of Main. If we have Advanced store a reference to Main, then Advanced would not be trivially copy/moveable. And therefore, any class that stores it as a member would not be trivially copy/moveable. By returning a constructed object, we allow Main to be trivially copy/moveable regardless of how Advanced is implemented.

Of course, there are downsides:

• We lose const-correctness. Notice how Adv has no const version. That's because it really can't have a const version. Since we're returning an object rather than a reference to one, a user can always do this:

  Advanced var = some_main.Adv();
  

  This will work even if some_main is const. If Advanced were a member, then the const could propagate correctly.

Answer 3

I'm not sure it's the best way to do things, but this might be a place where you could use (or abuse, depending on your viewpoint) multiple inheritance:

class basic_button {
    virtual void basic_func1() = 0;
    virtual void basic_func2() = 0;
};

class graphic_button { 
    virtual void graphic_func1() = 0;
    virtual void graphic_func2() = 0;
};

class expert_knobs {
    virtual void expert_func1() = 0;
    virtual void expert_func2() = 0;
};

class button : public basic_button, public graphic_button, public expert_knobs {
// ...
};

This way the button class itself is a fairly simple, straightforward object we've segmented the interface into pieces, and we can (for example) have separate documentation for basic_button, graphic_button, and so on. At the same time, the actual object we create is just a single, simple object so we don't need to try to coordinate lifetimes of multiple objects and such to get correct behavior.

At the same time, I can't help thinking that the basic idea here is largely broken. This strikes me as largely a documentation problem, which should be dealt with via decent documentation that just has a number of sections:

Basic Operations

documentation of basic operations here

Advanced Operations

documentation of advanced operations here

etc.

Answer 4

Use interface segregation for this purpose

Create separate interface classes, one with Basic functionality & the other with Advanced functionality. Generally the Advanced might inherit from Basic interface, not mandatory though.

Implement a concrete class which inherits from these two and implements both interfaces. Depending on which interface is provided, the user will be restricted to a specific mode.

As in the below code, different interfaces offer different segments of the functionality to the user.

#include <iostream>
using namespace std;

struct BasicMaths
{
    virtual int Sum(int a, int b) = 0;
    virtual int Difference(int a, int b) = 0;
    virtual int Product(int a, int b) = 0;
    virtual float Division(int a, int b) = 0;
};

struct TrigoMaths
{
    virtual double Sine(double angle) = 0;
    virtual double Cos(double angle) = 0;
    virtual double Tan(double angle) = 0;
};

struct AdvancedMaths: public BasicMaths, public TrigoMaths
{
};

class Math:public AdvancedMaths
{
public:

    int Sum(int a, int b)
    {return a+b;}
    int Difference(int a, int b)
    {return a-b;}
    int Product(int a, int b)
    {return a*b;}
    float Division(int a, int b)
    {return a/b;}
    double Sine(double angle)
    {return angle;}
    double Cos(double angle)
    {return angle;}
    double Tan(double angle)
    {return angle;}
};

int main()
{
    BasicMaths* bm = new Math();

    //// Basic Maths ///////////////////////////////////////////////////////
    //These will work fine
    cout << "Sum : " << bm->Sum(10, 5) << endl;
    cout << "Difference : " << bm->Difference(10,5) << endl;
    cout << "Product : " << bm->Product(10, 5) << endl;
    cout << "Division : " << bm->Division(10, 5) << endl;

    //These won't work as 'bm' doesn't have these interfaces
    //cout << "Sine : " << bm->Sine(90) << endl;
    //cout << "Cos : " << bm->Cos(90) << endl;
    //cout << "Tan : " << bm->Tan(90) << endl;


    ////Trigo Maths  ///////////////////////////////////////////////////////
    //These will work fine
    TrigoMaths* tm = dynamic_cast<TrigoMaths*>(bm);

    cout << "Sine : " << tm->Sine(90) << endl;
    cout << "Cos : " << tm->Cos(90) << endl;
    cout << "Tan : " << tm->Tan(90) << endl;

    //These won't work as 'tm' doesn't have these interfaces
    //cout << "Sum : " << tm->Sum(10, 5) << endl;
    //cout << "Difference : " << tm->Difference(10,5) << endl;
    //cout << "Product : " << tm->Product(10, 5) << endl;
    //cout << "Division : " << tm->Division(10, 5) << endl;


    //// Advanced Maths  ///////////////////////////////////////////////////////
    AdvancedMaths* am = dynamic_cast<AdvancedMaths*>(tm);

    //All interfaces work fine here
    cout << "Sum : " << am->Sum(10, 5) << endl;
    cout << "Sine : " << am->Sine(90) << endl;

    return 0;
}

. . .