Sandbox:Piffpoof2b

=Moderate PySide Examples=

Purpose
The purpose of this page is to cover Moderate level examples of the PySide GUI manager (accompanying pages cover aspects that are both more or less advanced). An example program is used to cover the different PySide topics. The intention is to present some functional PySide code so anyone who needs to use PySide can copy out the relevant section, modify and adapt it to their own purposes.

Code Based Discussion - Declarative Portion
The "example program" is actually a large class definition, the definition of a PySide GUI class and has over 150 lines of code (including comments). There is no functional purpose to the Class or it's behaviour, the sole purpose is to demonstrate possible GUI actions and present some code that hopefully can be used by other FreeCAD users.

The Class definition and the small number of lines of code that invoke are described in the order the occur in the file. This order is based on the screen layout which is rather arbitrary and solely intended to demonstrate features. This is the GUI screen the PySide CLass generates:

Most of the remainder of this page will describe the contents of the Class definition which appears at the end of this section. First we will cover the declarative elements that define how things operate and how the GUI is assembled, then we will cover the operative sections (i.e. the code that will execute when user interactions occur).

Import Statement
The mandatory Import statement

This is best placed at the top of the Python file.

Class Definition
This code is best copied out verbatim and altered. The gist of the code is that we are sub-classing the QDialog Class of PySide. In adapting this code you will want to change the class name "ExampleGuiClass" - make sure to change it in both locations (e.g. lines 1 & 4).

Window Return Status
This is not mandatory but rather a good programming practice, this sets a default return status for the window which will be there regardless of what the user does. Later in the code this may be changed by the Python code to indicate different options the user may have selected.

Window Creation
Remembering that screen dimensions are measured from the upper-left corner, on the 3rd line the values refer to: The title of the window is set and the final line simply means that this window will never be obscured by another window - if this is not desired then simply place a Python comment character ('#') as the first character of the line.
 * the number of pixels the upper-left corner will be to the right of the lefthand screen edge (250)
 * the number of pixels the upper-left corner will be below the upper screen edge (250)
 * the width of the screen in pixels (400)
 * the height of the screen in pixels (350)

Label Creation
In PySide labels serve two purposes, static labels (as the name implies) as well as read-only (i.e. display-only) text fields. So unchanging instructions to the user such as "Don't push the red button" as well as dynamic calculation results such as "42" can be communicated to the user. The 2nd line declares a Label and sets it's initial value (which is blank in this case). The 3rd line specifies the font, any font (on the system) can be specified, if not specified the default font is used. In this case the font is specified as a non-proportional one. The label is moved to it's location in the window - it's coordinates specify it's position with respect to the window (not the screen).

Checkbox Creation
Checkboxes can be off and on in any combination (unlike radio buttons). Line 2 declares one and set's it initial Value. Line 3 specifies which method will be executed when the Checkbox is clicked (in this case the method 'onCheckBox1'). If the 4th line did not have the Python comment character ('#') as the first character, then it would be executed and it would mark the checkbox as checked. Finally the 5th line moves the Checkbox into position.

Radio Button Creation
The creation of the Radio BUttons is very similar to the Checkboxes. The only difference really is the behaviour of the Radio Buttons in that only one of them can be 'on' at a time.

Pop-Up Menu Creation
In line 2 a list is built up of what will be the user choices. An alternative is to build up a Dictionary but only use the Keys for the list of menu choices. Line 4 creates the pop-up menu (known as a ComboBox to PySide), the user options are added in line 5.

As a side note, if the Dictionary was used then the lines would appear as:

Returning to the main code sample for this section, line 6 sets the default choice, this line may be omitted, also the value of the default choice could be loaded into the corresponding Label (once again if appropriate). And finally the move into position at line 8.

Button Creation Part 1
The button is created in line 2 with it's name, the handler for it's signal when clicked is specified in line 3. Line 4 is there to prevent the button from becoming the 'default button' - the button that will be clicked if the user simply presses the Return key. And a move to position finished up the code segment.

Text Input Creation
The QLineEdit widget is probably the most common for user textual input, in this example the code section after this one will set up a contextual menu to operate on it. This code section creates (line 2), sets an initial value (line 3), sets a width to the field (line 4) and moves the widget into place (line 5).

Contextual Menu Creation
This code has numerous repetitions as the same action is performed with different values - this is part of what makes GUI code so lengthy (no matter what the system). First a QAction is created - it is a pairing (or linkage) of the text that the user will see as their selectable option along with the method that will execute if they select that option. It is basically a pairing of a user choice with a piece of code. Line 3 creates it, line 4 defines the user option (as they will see it) and line 5 specifies which piece of Python code will execute.

Skipping to line 19 (the line with "self.textInput.setContextMenuPolicy") a ActionsContextMenu is created which is holder for all the separate QAction linkages between user choice and code to execute. Each widget can only have a single Contextual Menu (i.e. the menu associated with the right-click) so line 19 defines that menu. The following 4 lines add the linkages created at the beginning of this code section. Order is significant here, the user will see the menu options in the order they are added. Notice that the 3rd menu option is really a bit of nothing, it's code is null but it serves to separate 2 groups of options on the Contextual Menu.

Numeric Input Creation
The creation of the field for numeric input really follows that for Text Input earlier. In fact the code is identical with exception of the 3rd and 4th lines. The 3rd line sets the Mask as defined by PySide, which in this case specifies up to 3 digits (which may include 0).

Button Creation Part 2
Both buttons are created with a name (which will appear as their label), associated with a method which will execute when they are clicked, and moved into position. The one exception is line 4 which specifies the 'Cancel' button as the default button - that means it will be "clicked" if the user preses the Return key.

Window Display
There is only one line and it causes the GUI to be displayed after the setup.

Code Based Discussion - Operative Portion
We now move onto the operative portion of the GUI definition which is the code that executes in response to user interactions with the GUI.

Misc Additional Topics

 * set window maximise/normal/minimise
 * set window to top
 * geometry
 * frame