+ Widget::Contains()

Author: oktonion

src/Widget.cpp

@@ -496,6 +496,29 @@ void Widget::BringToFront()
 	PtWidgetToFront(widget());
 }
 
+bool Widget::Contains(const Widget &widget)
+{
+	PtWidget_t *this_widget = this->widget();
+
+	if(false == PtIsContainer(this_widget))
+		return false;
+	
+	PtWidget_t *front = PtWidgetChildFront(this_widget);
+
+	if(NULL == front)
+		return false;
+	
+	PtWidget_t *other_widget = widget.widget();
+
+	for(PtWidget_t *next = front; next != NULL; next = PtWidgetBrotherBehind(next))
+	{
+		if(next == other_widget)
+			return true;
+	}
+
+	return false;
+}
+
 void Widget::SetBounds(short x, short y, unsigned short width, unsigned short height)
 {
 	PhDim_t size;
@@ -525,18 +548,25 @@ bool Widget::Focus()
 	return PtGiveFocus(widget(), nullptr) != nullptr;
 }
 
-Widget Widget::GetNextWidget(Widget widget, bool forward) const
+Widget Widget::GetNextWidget(const Widget &widget, bool forward) const
 {
 	PtWidget_t *this_widget = this->widget();
 
 	PtWidget_t *result = 
 		forward ? 
-			PtWidgetChildFront(this_widget):
-			PtWidgetChildBack(this_widget);
+			PtWidgetBrotherInFront(this_widget):
+			PtWidgetBrotherBehind(this_widget);
 
 	if(NULL == result)
-		throw(
-			std::out_of_range(std::string("PhWidgets::Widget::GetNextWidget(): \'") + WidgetClassName(this_widget) + "\' widget has no children"));
+	{
+		result = 
+		forward ? 
+			PtWidgetBrotherBehind(this_widget):
+			PtWidgetBrotherInFront(this_widget);
+	}
+
+	if(NULL == result)
+		return *this;
 
 	return Widget(result);
 }

src/Widget.h

@@ -1092,6 +1092,36 @@ namespace PhWidgets
 		*/
 		void BringToFront();
 
+		//! Retrieves a value indicating whether the specified widget is a child of the widget.
+		/*!
+			@param[in] widget The Widget to evaluate.
+			@returns `true` if the specified widget is a child of the widget; otherwise, `false`.
+
+			### Examples ###
+
+			The following code example ensures that a Label is visible by calling its BringToFront() method. 
+			This example requires that you have a Window `main_window` with a Label named `label1`.
+
+			@code
+				void MakeLabelVisible()
+				{
+					// If the window contains label1, bring it 
+					// to the front to make sure it is visible.
+					
+					if(main_window.Contains(label1))
+					{
+						label1.BringToFront();
+					}
+				}
+			@endcode
+
+			@see
+			- BringToFront()
+			- SendToBack()
+			- Widgets
+		*/
+		bool Contains(const Widget &widget);
+
 		//! Sets input focus to the widget.
 		/*!
 			@return `true` if the input focus request was successful; otherwise, `false`.
@@ -1145,7 +1175,7 @@ namespace PhWidgets
 			- Container::ActiveWidget
 			- Widgets
 		*/
-		Widget GetNextWidget(Widget widget, bool forward = true) const;
+		Widget GetNextWidget(const Widget &widget, bool forward = true) const;
 
 		//! Sends the widget to the back of the z-order.
 		/*!