GUIzero Widget Programming

[last updated: 2025-11-15]
GUIzero home page
(link to:) Github: widget documentation
widget Colors
-----

... this page is very much a mess of in-process notes ...






      On This Page:
• Introduction;
• Creating and modifying Widgets:

---------------------------------------------------------
• Introduction:
  • A GUIzero/python GUI program starts with an App object. This is the first thing that is created.
    It is a container, and you put other objects (Widgets) into it.
  • A widget is an object that gets placed into a container.
  • The App object is a container, but not all widget types are containers.
    When you add a widget to your program, you must put it into a container.
    You can put it into an App object, or a Window or a Box widget.
  • When you first start your program, the first thing you do is create a main window (App).
    It is a container, and that's where your first widgets must be placed.
    You then proceed to add other widgets as desired to construct your GUI.
    These subsequent widgets can be placed in your original App object, or they can be put into any other container/object that you have placed in your App.
  • So in the end you have a set of nested objects, starting with the initial App, other objects in the App, other objects in those objects, other objects nested in those objects, etc.

  • layout:
    • This is a key concept that you must understand.
      Layout is a property of all container widgets.
      It has two possible values: "auto" (default) and "grid"
          box3 = Box(mainW, height=700, width=500, layout="grid")
      Its value determines the protocol that guizero uses to decide "where" inside the parent widget, your new widget will be placed.

  ---------------------------------------------------------

• Widgets:
  • First create your main window:
    Since all widgets you create must be placed into some object/container/parent,
    you must start by creating your main window:
        mainW = App(title="this is the title of the main window", height=700, width=500)
    The 'mainW' is your choice of variable name. Many people use 'app'. I find this confusing and prefer 'mainW'. But it's your choice regardless.

  • Create a widget - General syntax:
    [widgetVarName] = [widgetName] ( [masterName], [parameters], ... )
    • [widgetVarName] is your choice of variable name to attach to the widget so you can manipulate it later in your program.
    • [widgetName] is any one of the 14 or so pre-defined widget types that you want to use.
    • [masterName] is the name of the container (the parent container) that will hold your new widget.
      This is the one required parameter for all widgets, except the initial App object, which has no parent, but does require a title.
    • [parameters] are any number of things you want to specify to define your widget.
    • If your parent widget has "grid" layout, then one of the parameters you must specify when you create your widget
      is: grid=[x, y]
      eg. if you are creating a widget with a parent that has a grid layout, you might do something like this:
          PB1 = PushButton(mainW, grid=[2, 1], command=doSomething)

  • Examples:
    • Box:
      The parent "mainW" is the minimum required parameter, but you really should also specify height and width:
          box1 = Box(mainW, height=100, width=200)
      ----------
    • PushButton:
      •     PB1 = PushButton(mainW, command=doSomething)
        Notice the doSomething is NOT in quotes. This is the function that gets executed when you click on the PB.
        Therefore you must have a function defined with the doSomething name, eg.
            def doSomething():
                [some statements]
                return
      • text - to be displayed on the face of the PB:
            PB1 = PushButton(mainW, text="click here", command=doSomething)
      • visible and enabled - True or False (default True)

    ---------------------------------------------------------

  • Modifying a widget's properties after it's created:
    I find this field too complicated for any easy description and understanding,
    so instead I'll just use examples:
    • Box:
    • PushButton:

    ---------------------------------------------------------

  • PushButton:
    • Parameters:
      These are the things that can be specified when you create the widget:
      • height and width - in characters or "fill" to span the full dimension of its containing widget
      • padx and pady - pixels of spacing between edge of PB and any text placed in it

    • Using tk.config:
      • PB1.tk.config(borderwidth = 6)
      • bg - background color
      • align
      • enabled and visible - True or False
      • font - a string name of the font style of the text on the button
      • grid - [x,y] coordinates of this widget in its container's grid
      • height and width - in characters or pixels (???) or "fill"
      • image - string of path to image
      • master
      • text - string to be displayed
      • text_color
      • text_size - in pixels
      • tk - tkinter.Button - The internal tkinter object, see Using tkinter
      • value - int - returns 1 when the button is pressed, else 0

    ----------

  -----------------------------------------------------

• Layout:
  How/where will your widgets be placed?
  • An important concept to understand:
    • When you create a widget, you must put it inside a container.
      App, Window, and Box objects in your system can all act as containers (masters) to contain other widgets.
    • The first object you create is your mainWindow. It must be done with the App module:
      mainWindow = App()

  • Every subsequent object/widget you create will be placed inside some already existing container (App, Window, or Box).
    This is specified with the first parameter (the 'master' parameter) in your widget definition statement:
    widget2Box = Box(mainWindow)
  • The second object you define (we'll call this your first widget) must be inside your mainWindow, because that's the only container you have when you start.
    Now when you create your second widget, whatever it may be,
    you may have a choice of which container to put it into.
    If your first widget is a Box or a Window or an App, then it can act as a container for your second widget.
    In that case, when you define your second widget, you can choose whether to put it into your original mainWindow (App),
    or whether to put it into your first widget (assuming it's a Box, or a Window, or an App object).
    widget3Box = Box(mainWindow)
    -or- widget3Box = Box(widget2Box)
  • Exact position/placement inside the container where your new widget will be placed
    is determined by the "layout" and other properties that you specify when you create the containers.
  • The "layout" parameter can be either "auto" or "grid"
    • Layout is set when you define your object/widget/window. For example:
      mainWindow = App(layout="auto")
    • If you specify an "auto" layout (the easiest/simplest), for your object/container, then
      widgets placed in it will be centered and stacked vertically
      (unless it's a box and you've specified something different with the "align" parameter).

eof