From f0130fd591b261ea48f45b858d57af01429f63bf Mon Sep 17 00:00:00 2001 From: Rym Bouabid Date: Tue, 14 Nov 2023 16:02:04 +0100 Subject: [PATCH] Doc: Improve documentation for QObject::findChild There is a difference between findChild() and findChild("") that was not explained in the documentation. So, add a sentence to clarify it. The object's search when there are several direct ancestors was documented as "undefined". Change it to "first child in children()". Task-number: QTBUG-103986 Pick-to: 6.5 Change-Id: I25cb01b87d3b24af498ad494b3f353840ee78807 Reviewed-by: Marc Mutz (cherry picked from commit 80cdd4e5bbe15ef3235b1269b3781f8e4b19a5fa) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/kernel/qobject.cpp | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp index 7a96918f0c6..4332119ac88 100644 --- a/src/corelib/kernel/qobject.cpp +++ b/src/corelib/kernel/qobject.cpp @@ -1982,14 +1982,15 @@ void QObject::killTimer(int id) Returns the child of this object that can be cast into type T and that is called \a name, or \nullptr if there is no such object. - Omitting the \a name argument causes all object names to be matched. + A null \a name argument causes all objects to be matched. An empty, + non-null \a name matches only objects whose \l objectName is empty. The search is performed recursively, unless \a options specifies the option FindDirectChildrenOnly. - If there is more than one child matching the search, the most - direct ancestor is returned. If there are several direct - ancestors, it is undefined which one will be returned. In that - case, findChildren() should be used. + If there is more than one child matching the search, the most-direct + ancestor is returned. If there are several most-direct ancestors, the + first child in children() will be returned. In that case, it's better + to use findChildren() to get the complete list of all children. This example returns a child \c{QPushButton} of \c{parentWidget} named \c{"button1"}, even if the button isn't a direct child of