diff --git a/.gitignore b/.gitignore index 1701d511..5c87a561 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ doc/html snap/parts/ snap/prime/ snap/stage/ +doc/interfacelist.qdoc diff --git a/doc/interfaces.qdoc b/doc/interfaces.qdoc new file mode 100644 index 00000000..90f53990 --- /dev/null +++ b/doc/interfaces.qdoc @@ -0,0 +1,37 @@ +/*! + \page interfaces.html + \brief Interfaces define how a DeviceClass behaves + + \section1 Interfaces for DeviceClasses + + When creating a DeviceClass, the interfaces field can be used to specify a list of interfaces this DeviceClass implements. + + When implementing an interface, the DeviceClass must follow the interface specification for the according interface. This means + the DeviceClass needs to have at least all the \l{StateType}{states}, \l{ActionType}{actions} and \l{EventType}{events} the given interface requires. A DeviceClass may + add custom states, actions or events, or even implement multiple interfaces. + + The main purpose of interfaces is to provide for a better user experience. Using interfaces, a plugin developer can suggest the + ui to be used for this DeviceClass. For example, having a plugin that can control a dimmable light would likely have a state + named "powered" of type boolean and one named "brightness" of type int, ranging from 0 to 100%. Having just this information, + the ui would create a generic switch component to flip the bool state and a generic slider component to allow adjusting the + brightness because it can't know what the actual switch or slider do. For a better user experience though, the plugin developer + could just add the interface "dimmedlight" to this deviceclass and this way tell the ui that this actually is a dimmed light. + The ui can use this information to paint a pretty brightness slider, and implicitly flip the power switch off when the brightness + slider is moved to the lower end. + + Another purpose of interfaces is to help the ui grouping and managing device classes. For example the \l {gateway} interface does + not require to implement any properties, however, it tells the ui that this is a gateway and thus not relevant to show to the + user in the main control entity. Instead, gateways might be listed in the configuration section of the client application. + + In general it is a good idea to follow as many interfaces as precicely as possible in order to provide for the best user experience. + + A interface can extend another interface. For example, the \l {light} interface only requires one state called powered of type bool. + A dimmablelight extends this type and adds a brightness property to it. This means, if a DeviceClass implements \l {dimmablelight}, it + also needs to cater for the \l {light} interface's states. + + + \section1 Currently available interfaces + \include interfacelist.qdoc + + +*/ diff --git a/doc/plugin-json.qdoc b/doc/plugin-json.qdoc index 8fc9710f..f8f9a393 100644 --- a/doc/plugin-json.qdoc +++ b/doc/plugin-json.qdoc @@ -141,6 +141,7 @@ "idName": "deviceClassName", "id": "uuid", "o:deviceIcon": "Icon", + "o:interfaces": [ "String" ], "o:basicTags": [ "BasicTag" ], @@ -174,6 +175,7 @@ \li - \underline{\e name:} The visible name of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::name()}. \li - \underline{\e idName:} This parameter will be used to define the DeviceClassId variable named DeviceClassId in the plugininfo.h, so it can be used in the code. \li - \underline{\e id:} The actual uuid (\l{DeviceClassId}) of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::id()}. + \li - \underline{\e interfaces: } A list of \l{Interfaces for DeviceClasses}{interfaces} this plugin implements. \li - \underline{\e basicTags:} A list of \l{DeviceClass::BasicTag}{BasicTags} for this device \unicode{0x2192} \l{DeviceClass::basicTags()}. A \l{DeviceClass} can have multiple \l{DeviceClass::BasicTag}{BasicTags} which describe the basic category of the DeviceClass. A \l{DeviceClass} should be eighter a Service or a Device, never both. See enum \l{DeviceClass::BasicTag} for more information. The expected value for the \e basicTags parameters matches the enum name like this: \tt {DeviceClass::BasicTagService} \unicode{0x2192} \tt {"basicTags": [ "Service" ]} diff --git a/guh.pro b/guh.pro index b612637a..319fe59a 100644 --- a/guh.pro +++ b/guh.pro @@ -25,7 +25,8 @@ tests.depends = libguh doc.depends = libguh server # Note: some how extraimages in qdocconf did not the trick -doc.commands = cd $$top_srcdir/doc; qdoc config.qdocconf; cp -r images/* html/images/; \ +doc.commands += cd $$top_srcdir/libguh/interfaces; ./generatedoc.sh; +doc.commands += cd $$top_srcdir/doc; qdoc config.qdocconf; cp -r images/* html/images/; \ cp -r favicons/* html/; cp -r $$top_srcdir/doc/html $$top_builddir/ licensecheck.commands = $$top_srcdir/tests/auto/checklicenseheaders.sh $$top_srcdir diff --git a/libguh/interfaces/gateway.json b/libguh/interfaces/gateway.json new file mode 100644 index 00000000..0db3279e --- /dev/null +++ b/libguh/interfaces/gateway.json @@ -0,0 +1,3 @@ +{ + +} diff --git a/libguh/interfaces/generatedoc.sh b/libguh/interfaces/generatedoc.sh new file mode 100755 index 00000000..f3eddbb7 --- /dev/null +++ b/libguh/interfaces/generatedoc.sh @@ -0,0 +1,16 @@ +#!/bin/sh + +out_file=../../doc/interfacelist.qdoc +cur_dir=`pwd` +echo > $out_file +echo "\\list" >> $out_file +for i in `ls *.json`; do + echo "\\li \l{$i}" | sed s/\.json// >> $out_file +done +echo "\\endlist" >> $out_file + +for i in `ls *.json`; do + echo "\\\target $i" | sed s/\.json// >> $out_file + echo "\\section2 $i" | sed s/\.json// >> $out_file + echo "\\quotefile $cur_dir/$i" >> $out_file +done diff --git a/libguh/interfaces/interfaces.qrc b/libguh/interfaces/interfaces.qrc index 99218d01..c8f1d169 100644 --- a/libguh/interfaces/interfaces.qrc +++ b/libguh/interfaces/interfaces.qrc @@ -5,5 +5,6 @@ dimmablelight.json colorlight.json garagegate.json + gateway.json