Skip to content

What We Know About QComboBox

Jump to bottom
russ_hensel edited this page Mar 31, 2026 · 3 revisions
Table of Contents

Introduction

A QComboBox is a drop-down list box (also known as a combo box or DDL) used in GUI applications to let the user select one item from a list. Combo boxes may also support editing, allowing users to type in values that are not in the list.

By reading the docs we have discovered that a QComboBox may be populated by strings, and the string is identified either by its value or by its position in the list ( zero-indexed ), and ( this is the new part for us ) by any one of various QT models. So this topic is going to require more than one tab to cover QComboBox uses. A new model based tab will be documented by What We Know About QComboBox with Model and the documentation below for the text based box will be moved to What We Know About QComboBox with Strings -- for now that documentation stays here.

This tab demonstrates and documents the use of the QComboBox widget in a QTPY application. Two combo boxes are used and controlled by several methods that mutate their appearance and behavior.

The key points:

  • When clicked, combo boxes expand to show their entire list of values.
  • When one item on the list is clicked, combo boxes shrink to show only the one selected value.
  • They can be editable, meaning the user can type new values.
  • They emit signals when the user changes selection or enters text.
  • They can be modified at runtime, with items added, removed, or reloaded.

Like other tabs in this application, this is a reference tab, showing expected widget behavior and tab structure.

📄 Code file:
qt5_by_example/tabs/basic_widgets/tab_q_combo_box.py
💡 View it in your IDE for full effect.

The documentation includes detailed comments in _build_gui_widgets() and the various mutate_ methods. This is part of the tab documentation pattern used throughout the project. See also: Tab Framework Code.

Interactions

Try the following actions on this tab:

  • Use the dropdown in combo_1 to select values from a predefined list.
  • In combo_2, type a custom value and press Enter.
  • Press the "combo\n_reload" button to clear and reload combo_1.
  • Use the mutate button to explore different programmatic changes to the combo boxes.
  • Observe the signal messages logged in the text area below the widgets.
  • Use Inspect to examine internal state.

What You Can Observe

  • combo_1 is a static dropdown list.
  • combo_2 is editable, supporting typed input.
  • Text changes and index changes trigger signal handlers.
  • Mutate methods alter content, selection, or visibility.
  • You can inspect widget properties via mutate_3() and inspect().

Important Methods

_build_gui_widgets(self, main_layout)

Initializes two combo boxes:

  • combo_1 is filled with static items and starts with "Two" selected.
  • combo_2 is editable and also preloaded with values.
  • Both combo boxes are connected to currentIndexChanged and currentTextChanged handlers.
  • Adds a reload button and other standard controls.

mutate_0()

  • Modifies combo_2 using .lineEdit().setText().
  • Logs the current text of combo_1.

mutate_1() and mutate_2()

  • Sets values for `combo

Clone this wiki locally