/*
    signal-slot.qdoc

    This file is part of the GammaRay documentation.

    Copyright (C) 2016 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com
    Author: Volker Krause <volker.krause@kdab.com>

    Licensees holding valid commercial KDAB GammaRay licenses may use this file in
    accordance with GammaRay Commercial License Agreement provided with the Software.

    Contact info@kdab.com if any conditions of this licensing are not clear to you.

    This work is also licensed under the Creative Commons Attribution-ShareAlike 4.0
    International License. See <http://creativecommons.org/licenses/by-sa/4.0/>.
*/

/*!
    \example signal-slot
    \title Signal/Slot Connections
    \brief Investiagte issues regarding signal/slot connection handling.
    \ingroup examples-gammaray

    This examples shows GammaRay's capabilities in analyzing signal/slot connection problems.

    \section1 Problem

    The application shows two buttons and a LCD widget. The LCD widget is connected to the clicked()
    signal of the first button and increments every time the clicked() signal is emitted. The second
    button recreates the connection.

    Clicking the reconnect button multiple times however breaks things, so that clicking the emit button
    will result in more than on increment of the LCD widget.

    \snippet signal-slot/signal-slot.cpp Widget setup

    \section1 Investigation

    There are several aspects of this problem that can be analyzed with GammaRay.

    \section2 Watch a signal emission

    Select the emit button in the \l{Object Inspector} or the \l{Widget Inspector} tool, and open the Methods tab on the right.
    Find the clicked() signal in the method list, and chose "Connect to" in the context menu.
    Clicking on the emit button will now show each emitted clicked() signal in the method log at the bottom half on
    the right side. This allows you to verify that the signal is emitted correctly, and here in particular is only
    emitted once per click.

    Alternatively, you can also observe this in the \l{Signal Plotter} view.

    \section2 Check existing signal/slot connections

    Select the emit button in the \l{Object Inspector} or the \l{Widget Inspector} tool, and open the Connections tab on the right.
    The list of outbound connections at the bottom half will show all existing connections to the LCD widget incrementing code.
    You will notice that multiple connections to the same slot exist, and that GammaRay shows a warning icon for this.

    Looking at the reconnection slot we then see that the code mixes string based and function pointer based connect()/disconnect()
    calls, which is not supported by QObject:

    \snippet signal-slot/signal-slot.cpp Mismatching reconnect

    This code therefore adds another connection each time its called, resulting in multiple increments in the LCD widget per emit
    button click.
*/
