1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
# Documentation for Python Extension Authors
This document is intended to provide an introduction to writing Python extensions
for the QtCreator.
## Importing QtCreator specific modules
Currently, the bindings are available from Python under the following names:
```Python
from PythonExtension import QtCreator # Imports the generated module for the typesystem
from PythonExtension import PluginInstance # Imports the plugin instance
```
## `PythonExtension.PluginInstance`
This is the Python binding for the extension manager that works on the C++ side. It provides the
following functions, that can (and should) be used from Python:
```Python
from PythonExtension import PluginInstance as inst
# Returns a PySide QDir which points to the extension directory
inst.extensionDir()
# Returns a list with the names of all Python extensions
# If loaded only is supplied as True, only extensions that
# where loaded successfully are returned
inst.extensionList(loadedOnly = False)
# Mark an extension as loaded
# This should normally not be used and exists mainly
# for use by the extension manager
inst.flagAsLoaded("name_of_extension")
# Returns the path of the custom location to
# where missing dependencies should be pip installed
inst.pythonPackagePath()
```
# QtCreator bindings
Generally, the parts of QtCreator that are exposed have an interface that is nearly
identical to the C++ interface.
## Working with Menus
You can add new items to the menus of QtCreator. You can either add an action directly, or
add a new action container, that holds a sub-menu.
### Adding a sub menu
The following code snippet illustrates how to add a new menu.
```Python
from PythonExtension import QtCreator
def hello():
print("Hello World.")
# By convention, the menuId starts with "Python"
menuId = "Python.SmallMenu.Menu"
menu = QtCreator.Core.ActionManager.createMenu(menuId)
menu.menu().setTitle("My menu")
menu.menu().addAction("My action", hello)
# Add our new menu to the "Tools" menu in QtCreator
QtCreator.Core.ActionManager.actionContainer("QtCreator.Menu.Tools").addMenu(menu)
```
### Adding a new action directly
The following code snippet illustrates how to add a new action to an existing action container.
```Python
from PythonExtension import QtCreator
def hello():
print("Hello World.")
# Add a new action to the "Tools" menu
menu = QtCreator.Core.ActionManager.actionContainer("QtCreator.Menu.Tools")
menu.menu().addAction("My action", hello)
```
### Menu Id list
Currently, the following menu ids are available in QtCreator.
```Python
"QtCreator.Menu.File"
"QtCreator.Menu.File.RecentFiles"
"QtCreator.Menu.Edit"
"QtCreator.Menu.Edit.Advanced"
"QtCreator.Menu.Tools"
"QtCreator.Menu.Tools.External"
"QtCreator.Menu.Window"
"QtCreator.Menu.Window.Panes"
"QtCreator.Menu.Window.ModeStyles"
"QtCreator.Menu.Window.Views"
"QtCreator.Menu.Help"
```
# The embedded Python interpreter
## Python modules and `sys.path`
When importing modules, the following important locations will be checked (in this order):
1. The folder of the extension itself (files and folders in your extension)
2. The system Python path entries (anything you `pip install`ed globally)
3. Qt Creator's python extension directory
4. The Qt Creator specific Python module directory
- Note: This is where you should install any dependencies missing
if you want to use non-standard Python packages / modules
- This last path is accessible with `PluginInstance.pythonPackagePath()`
## Reserved variable names
Names that look like
```Python
qt_creator_{SOME_NAME}_symbol_mchawrioklpilnjajqkfl
```
are reserved for the ExtensionManager. Unless you know exactly what you are doing, you should never
touch any of these variables.
## Installing dependencies
If you want to install dependencies, you can include a standard Python `requirements.txt`
file in your extension folder. **Note that this file is pip installed _once_.** After the initial
pip install, a new file called `requirements.txt.installed` is created in the extensions folder. To
run the install again, this file simply has to be deleted. **Be careful to remove this file, when
distributing your extension in a .zip file.**
Otherwise you can do any setup you need in your extension's initialization code.
|
