diff options
Diffstat (limited to 'sources/shiboken6/doc')
60 files changed, 10428 insertions, 0 deletions
diff --git a/sources/shiboken6/doc/CMakeLists.txt b/sources/shiboken6/doc/CMakeLists.txt new file mode 100644 index 000000000..46195417e --- /dev/null +++ b/sources/shiboken6/doc/CMakeLists.txt @@ -0,0 +1,62 @@ +cmake_minimum_required(VERSION 3.16) + +if(FULLDOCSBUILD EQUAL 0) + project(shiboken6_doc) +endif() +find_program(SPHINX sphinx-build DOC "Path to sphinx-build binary.") + +if (SPHINX) + message(STATUS "sphinx-build - found") + configure_file(conf.py.in conf.py @ONLY) + # conditional tag for sphinx build + #string(JOIN "_" SPHINX_TAG ${DOC_OUTPUT_FORMAT} "format") + add_custom_target(doc + COMMAND ${SPHINX} -b ${DOC_OUTPUT_FORMAT} -c . ${CMAKE_CURRENT_SOURCE_DIR} html + COMMENT "Generating HTMLs..." + VERBATIM) + # Python script that will be called to update the QHP + set(py_cmd "from __future__ import print_function +import fileinput +import re +try: +\tfor line in fileinput.input('html/Shiboken.qhp',inplace=True,backup='.bak'): +\t\tline_copy=line.strip() +\t\tif not line_copy: # check for empty line +\t\t\tcontinue +\t\tmatch=re.match('(^.*virtualFolder.)doc(.*$)',line) +\t\tif match: +\t\t\trepl=''.join([match.group(1),'shiboken6',match.group(2)]) +\t\t\tprint(line.replace(match.group(0),repl),end=' ') +\t\telse: +\t\t\tprint(line) +except: +\tpass\n") + file(GENERATE OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/py_script.py + CONTENT ${py_cmd}) + + # create a custom command to generate QCH + if(DOC_OUTPUT_FORMAT STREQUAL "qthelp") + file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/html/Shiboken.qhp QHP_FILE) + add_custom_command(TARGET doc POST_BUILD + COMMAND ${PYTHON_EXECUTABLE} py_script.py # ${CMAKE_CURRENT_BINARY_DIR}/html/Shiboken.qhp + COMMAND qhelpgenerator ${QHP_FILE} + COMMENT "Genereting QCH based on the QHP..." + VERBATIM) + endif() +else() + message(WARNING "sphinx-build - not found! doc target disabled") + if (WIN32) + # if jom is used and we have no sphinx, then jom will crash. + # so for windows, we always create a doc target (until jom gets fixed...) + add_custom_target(doc echo. + COMMAND echo +++ This is a fake build, to make 'jom' happy. + COMMAND echo +++ The documentation was _not_ built! + COMMAND echo. + ) + endif() +endif() + +if (NOT WIN32) + file(GLOB manpages "${CMAKE_CURRENT_SOURCE_DIR}/*.1") + install(FILES ${manpages} DESTINATION share/man/man1) +endif() diff --git a/sources/shiboken6/doc/README.md b/sources/shiboken6/doc/README.md new file mode 100644 index 000000000..2575eafd2 --- /dev/null +++ b/sources/shiboken6/doc/README.md @@ -0,0 +1,12 @@ +# Shiboken Documentation + +The documentation was written and needs to be generated +with [python-sphinx](http://www.sphinx-doc.org/en/master/) + +### Images + +The SVG diagrams use the Qt color scheme. +The font also follows Qt styling, and it is called `Titillium`. +It can be download from: +* https://fonts.google.com/specimen/Titillium+Web +* https://www.fontsquirrel.com/fonts/Titillium diff --git a/sources/shiboken6/doc/_templates/index.html b/sources/shiboken6/doc/_templates/index.html new file mode 100644 index 000000000..00ac64271 --- /dev/null +++ b/sources/shiboken6/doc/_templates/index.html @@ -0,0 +1,35 @@ +{% extends "layout.html" %} +{% set title = 'Overview' %} +{% block body %} +<div class="section"> + <h1>{{ project }} {{ version }}</h1> + + <p>{{ project }} is a plugin (front-end) for Generator Runner. It generates bindings for C++ libraries using CPython source code.</p> + + <h2>Documentation</h2> + <table class="contentstable" align="center" style="margin-left: 30px"><tr> + <td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/> + <span class="linkdescr">for a complete overview</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("faq") }}">FAQ</a><br/> + <span class="linkdescr">answers for frequent asked questions</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("commandlineoptions") }}">Command line options</a><br/> + <span class="linkdescr">explains the few flags used to change {{ project }} behaviour</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("typesystemvariables") }}">Type System Variables</a><br/> + <span class="linkdescr">describes the type system variables that could be used in user custom code</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("typeconverters") }}">Type Converters</a><br/> + <span class="linkdescr">describes how to define type converters</span></p> + </td> + <td width="50%"> + <p class="biglink"><a class="biglink" href="{{ pathto("codeinjectionsemantics") }}">Code Injection Semantics</a><br/> + <span class="linkdescr">explains how custom code injection is interpreted by {{ project }}</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("sequenceprotocol") }}">Sequence Protocol</a><br/> + <span class="linkdescr">support for python sequence protocol</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("ownership") }}">Object Ownership</a><br/> + <span class="linkdescr">object ownership features</span></p> + <p class="biglink"><a class="biglink" href="{{ pathto("wordsofadvice") }}">Words of Advice</a><br/> + <span class="linkdescr">Advice for binding developers and users.</span></p> + </td></tr> + </table> +</div> +{% endblock %} diff --git a/sources/shiboken6/doc/_templates/layout.html b/sources/shiboken6/doc/_templates/layout.html new file mode 100644 index 000000000..2e2e9e892 --- /dev/null +++ b/sources/shiboken6/doc/_templates/layout.html @@ -0,0 +1,29 @@ +{% extends "!layout.html" %} + +# Invert sidebars +{%- block sidebar1 %}{{ sidebar() }}{%- endblock %} +{%- block sidebar2 %}{%- endblock %} + +{%- block header %} +<div id="container"> +<div class="header"> + <div class="header_container"> + <div class="logo"><a href="http://www.pyside.org"><img alt="PySide" src="{{ pathto('_static/pysidelogo.png', 1) }}"/></a></div> + {{ relbar() }} + </div> +</div> +{%- endblock -%} + +{%- block footer %} + <div class="footer"> + <a href="http://www.qt.io/"><img src="{{ pathto('_static/logo_qt.png', 1) }}" alt="Qt" border="0" /></a> + <a href="http://www.python.org"><img src="{{ pathto('_static/logo_python.jpg', 1) }}" alt="Python" border="0" /></a> + </div> +</div> +{%- endblock %} + +# No top relbar. +{%- block relbar1 %}{%- endblock %} + +# No bottom relbar. +{%- block relbar2 %}{%- endblock %} diff --git a/sources/shiboken6/doc/_themes/pysidedocs/searchbox.html b/sources/shiboken6/doc/_themes/pysidedocs/searchbox.html new file mode 100644 index 000000000..55a972156 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/searchbox.html @@ -0,0 +1,12 @@ +{%- if pagename != "search" %} +<div id="searchbox" style="display: none"> + <h3>{{ _('Quick search') }}</h3> + <form class="search" action="{{ pathto('search') }}" method="get"> + <input type="text" name="q" id="q" size="18" /> + <input type="submit" value="{{ _('Go') }}" id="search_button" /> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </form> +</div> +<script type="text/javascript">$('#searchbox').show(0);</script> +{%- endif %} diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/bg_header.png b/sources/shiboken6/doc/_themes/pysidedocs/static/bg_header.png Binary files differnew file mode 100644 index 000000000..843e7e2c5 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/static/bg_header.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/bg_topo.jpg b/sources/shiboken6/doc/_themes/pysidedocs/static/bg_topo.jpg Binary files differnew file mode 100644 index 000000000..4229ae8db --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/static/bg_topo.jpg diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/fakebar.png b/sources/shiboken6/doc/_themes/pysidedocs/static/fakebar.png Binary files differnew file mode 100644 index 000000000..b45830e00 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/static/fakebar.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/logo_python.jpg b/sources/shiboken6/doc/_themes/pysidedocs/static/logo_python.jpg Binary files differnew file mode 100644 index 000000000..cd474efba --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/static/logo_python.jpg diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/logo_qt.png b/sources/shiboken6/doc/_themes/pysidedocs/static/logo_qt.png Binary files differnew file mode 100644 index 000000000..39a4a26f3 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/static/logo_qt.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/pyside.css b/sources/shiboken6/doc/_themes/pysidedocs/static/pyside.css new file mode 100644 index 000000000..f6a1c5ae4 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/static/pyside.css @@ -0,0 +1,2076 @@ +@import url('cookie-confirm.css') screen; + +/* -- admonitions -- */ + +div.admonition { + margin: 1.5em 0 1.5em; + padding: 0; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.admonition code { + font-family: inherit; +} + +p.admonition-title + p { + padding-left: 1em; +} + +div.admonition a:after { + content: ', '; +} + +div.admonition a:last-child:after { + content: ''; +} + +.body { + width: 100% +} +.bodywrapper .admonition p.admonition-title { + margin-bottom:5px +} + +.bodywrapper .admonition p { + margin:0 +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +div.warning, div.seealso, div.note { + padding: 6px 0px 6px 10px; + border: none; +} + +div.warning { + background-color: #ffe4e4; +} + +div.seealso { + background-color: #fff2d6; +} + +div.note { + background-color: #f3f3f4; +} + +table.docutils { + margin-right: auto; + margin-bottom: 10px; + border: none; + width: initial; +} + +table.docutils.colwidths-given td { + float: none; +} + +table.docutils th, +table.docutils td { + padding-left:0; + border: none; +} + +table.docutils td ul { + margin:0 +} + +table.docutils td ul > li { + margin: 0 0 0.5em; +} +h2 em { + float: right; + font-size: 10px; + position: relative; + top: -20px; +} + +.document { + padding-bottom: 20px; +} + +.documentwrapper { + margin-left: 255px; +} + +.body blockquote { + border: none; + padding-left: 0; + margin-bottom: 1.5em; +} + +.sphinxsidebar { + float: left; + width: 186px; + padding: 25px; + text-align: left; + background-color: #fff; +} + +.sphinxsidebar ul { + padding: 0px; + margin: 0px; + list-style-position: inside; +} + +.sphinxsidebar > ul { + padding: 0px; + margin: 0px; +} + +.sphinxsidebar ul li li { + margin-left: 10px; + padding: 0px; + font-size: 0.95em; +} + +.sphinxsidebar ul a, +.sphinxsidebar p.topless a { + word-break: break-word; +} + +.sphinxsidebar h3, .sphinxsidebar h3 a { + color: #333; +} + +.sphinxsidebar p.topless { + margin: 1em 0 1em; +} + +.pysidetoc ul { + list-style: none; + padding: 0px; + margin: 0px; +} + +.pysidetoc em { + font-style: normal; +} + +.pysidetoc strong { + display: block; + padding: 5px; + margin: 0 10px 10px 0; + border: none; + background-color: #e2e2e2; +} + +.section .docutils.container td { + float:left; +} + +.hide { + display: none; +} + +/* copy-notice */ +.document + p { + margin-left: 255px; + width: 70%; + font-size: 0.75em; + margin: 0 35px 15px 280px; +} + +#searchbox { + border-top: 1px solid #989898; + padding-top: 10px; + margin-left: -10px; + margin-right: -10px; + padding-left: 10px; + padding-right: 10px; +} + +#search_button { + border: 1px solid #3A393A; + background-color: #3A393A; + color: white; + cursor: pointer; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + +} + +form { + margin: 0px; + padding: 0px; +} + +#searchbox h3 { + padding: 10px 0 0 0; + margin-bottom: 5px; +} + +/* search field */ +form #q { + width: 136px; + /* height: 22px; */ + /* border: none; */ + margin: 0px; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + margin-top: 2px; + padding: 4px; + line-height: 22px; +} + +#search-results h2 { + display: none; +} + +#search-results h2 { + display: none; +} + +#search-results ul.search { + margin: 0px; + padding: 0px; +} + +ul.search div.context { + padding-left: 40px; +} + +#installation td { + text-align: center; + font-weight: bold; +} + +em { + color: inherit; + font-style:italic; +} + +/******** REL bar *********/ + +.related { + display: inline; +} + +.related h3 { + display: none; +} + +.align-center { + text-align: center; +} + +.contentstable { + width: 100%; +} + +.contentstable td { + padding-left: 30px; + vertical-align: top; +} + +p.biglink a { + font-size: 20px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +p.highlight-link { + margin-top: 10px; + font-size: 0.8em; +} + +#synopsis table, table.field-list { + margin: 1em 0 1em 0; +} + +table.field-list tr { + text-align: left; +} + +tt.descname { + font-size: 120%; + font-weight: bold; +} + +#functions ul, #virtual-functions ul, #slots ul, #signals ul, #static-functions ul { + margin: 0; + padding: 6px; + border: 1px solid #ddd; + border-radius: 0; + background-color: #e2e2e2; +} + +#functions p, #virtual-functions p, #slots p, #signals p, #static-functions p { + margin: 0; + padding: 0; +} + +#functions li, #virtual-functions li, #slots li, #signals li, #static-functions li { + list-style: none; + margin: 5px; + padding: 0; + font-size: 90%; +} + +#synopsis span.pre { + color: #009491; + font-weight: bolder; +} + +#detailed-description .class dt, +#detailed-description .method dt, +#detailed-description .staticmethod dt, +#detailed-description .attribute dt { + margin: 0px; + margin-bottom: 10px; + padding: 10px; + font-weight: bold; + background-color: #e2e2e2; + border: none; + border-radius: 0; +} + +#detailed-description dd > blockquote, +#detailed-description dd > .field-list { + font-family: 'Droid Sans Mono'; + font-size: small; + border-left: 10px solid #e2e2e2; + padding-left: 10px; + margin-bottom: 1.5em; +} + +#detailed-description dd > blockquote blockquote { + border: none; + padding: 0; +} + +#detailed-description .class .field-odd, +#detailed-description .method .field-odd, +#detailed-description .staticmethod .field-odd, +#detailed-description .attribute .field-odd { + margin: 0; + padding: 1px 0 0 0; + background-color: #ffffff; + +} + +#detailed-description .class .field-even, +#detailed-description .method .field-even, +#detailed-description .staticmethod .field-even, +#detailed-description .attribute .field-even { + margin: 0; + padding: 1px 0 0 0; + background-color: #ffffff; +} + +#detailed-description .class .field-odd li, +#detailed-description .method .field-odd li, +#detailed-description .staticmethod .field-odd li, +#detailed-description .attribute .field-odd li { + list-style: none; + margin: 0; + padding: 0; + +} + +#detailed-description .class .field-even li, +#detailed-description .method .field-even li, +#detailed-description .staticmethod .field-even li, +#detailed-description .attribute .field-even li { + list-style: none; + margin: 0; + padding: 0; +} + +#detailed-description .class .field-odd p, +#detailed-description .method .field-odd p, +#detailed-description .staticmethod .field-odd p, +#detailed-description .attribute .field-odd p{ + margin: 0; + margin-left: 20px; + +} + +#detailed-description .class .field-even p, +#detailed-description .method .field-even p, +#detailed-description .staticmethod .field-even p, +#detailed-description .attribute .field-even p{ + margin: 0; + margin-left: 20px; +} + +#detailed-description .class .field-odd p:last-child, +#detailed-description .method .field-odd p:last-child, +#detailed-description .staticmethod .field-odd p:last-child, +#detailed-description .attribute .field-odd p:last-child { + margin-bottom: 10px; + +} + +#detailed-description .class .field-even p:last-child, +#detailed-description .method .field-even p:last-child, +#detailed-description .staticmethod .field-even p:last-child, +#detailed-description .attribute .field-even p:last-child{ + margin-bottom: 10px; +} + +.document dl.attribute, +.document dl.class, +.document dl.method, +.document dl.staticmethod { + margin-top: 2em; +} + +.document dl.attribute dd, +.document dl.class dd, +.document dl.method dd, +.document dl.staticmethod dd { + padding-left: 1em; +} + +#detailed-description .attribute td:nth-child(1) { + font-family: 'Droid Sans Mono'; +} + +/* Qt theme */ +#navbar { + position:fixed; + top:0; + left:0; + z-index:100; + background:#fff; + width:100% +} +#navbar .container, .fixed .container { + max-width:1280px; + margin:0 auto; + padding:0 3.9%; /* 0? */ + position:relative; + overflow:visible +} +#navbar .navbar-header { + position:relative +} +#menuextras li a:hover span { + color: #41cd52; +} +/* new header */ +#mm-wrap, #mm-wrap #mm-helper, +#mm-wrap #mm-helper li.mm-item, +#mm-wrap #mm-helper a.mm-link { + -moz-transition: none; + -o-transition: none; + -webkit-transition: none; + transition: none; + -webkit-border-radius: 0 0 0 0; + -moz-border-radius: 0 0 0 0; + -ms-border-radius: 0 0 0 0; + -o-border-radius: 0 0 0 0; + border-radius: 0 0 0 0; + -webkit-box-shadow: none; + -moz-box-shadow: none; + -ms-box-shadow: none; + -o-box-shadow: none; + box-shadow: none; + background: none; + border: 0; + bottom: auto; + box-sizing: border-box; + clip: auto; + color: #090e21; + display: block; + float: none; + font-family: inherit; + font-size: 14px; + height: auto; + left: auto; + line-height: 1.7; + list-style-type: none; + margin: 0; + min-height: 0; + opacity: 1; + outline: none; + overflow: visible; + padding: 0; + position: relative; + right: auto; + text-align: left; + text-decoration: none; + text-transform: none; + top: auto; + vertical-align: baseline; + visibility: inherit; + width: auto; +} +#mm-wrap #mm-helper { + visibility:visible; + text-align:right; + padding:0 0px 0 0px +} +#navbar #mm-wrap #mm-helper li.mm-item { + border-right:solid #f3f3f4 1px; + padding-right:30px; + padding-left:30px +} +#navbar #mm-wrap #mm-helper li.mm-item > a:hover { + opacity: .5 +} +#mm-wrap #mm-helper > li.mm-item { + margin:0 0 0 0; + display:inline-block; + height:auto; + vertical-align:middle +} +#navbar #mm-wrap #mm-helper li.mm-item:nth-child(3) { + border-right:0 +} +#mm-wrap #mm-helper a.mm-link { + cursor: pointer +} +@media (max-width: 1279px) { + #navbar { + padding:0; + position:relative; + } + #navbar .container { + max-width:100% + } + .container { + padding:0 2% + } + .sphinxsidebar { + top: 16px !important; + } +} +#navbar .navbar-oneQt { + display:inline; + float:left; + width:31px; + color:#41cd52 +} +#navbar .navbar-oneQt:before { + content:attr(data-icon); + position:absolute; + top:14px; + left:0; + color:#41cd52; + font-family:'Qt Icons'; + line-height:1; + font-size:40px; + transition:all 0.3s ease-in-out; +} +#mm-wrap { + clear:both; + background:rgba(255, 255, 255, 0.1); + -webkit-border-radius:0px 0px 0px 0px; + -moz-border-radius:0px 0px 0px 0px; + -ms-border-radius:0px 0px 0px 0px; + -o-border-radius:0px 0px 0px 0px; + border-radius:0px 0px 0px 0px +} +#mm-wrap #mm-helper li.mm-item:last-child a { + background:transparent url("icon_avatar.png") 50% 50% no-repeat !important; + background-size:24px !important; + width:24px !important; + height:24px !important; +} +#navbar #mm-wrap #mm-helper li.mm-item > a { + opacity:1; + -webkit-transition:all 0.3s ease-in-out; + -moz-transition:all 0.3s ease-in-out; + -ms-transition:all 0.3s ease-in-out; + -o-transition:all 0.3s ease-in-out; + transition:all 0.3s ease-in-out; +} +#mm-wrap #mm-helper > li.mm-item > a.mm-link { + border-top:0px solid #fff; + border-left:0px solid #fff; + border-right:0px solid #fff; + border-bottom:0px solid #fff; + outline:none; + text-decoration:none; + padding:0 0 0 0; + line-height:70px; + font-weight:normal; + height:70px; + vertical-align:baseline; + text-align:left; + width:auto; + display:block; + color:#090e21; + text-transform:none; + text-decoration:none; + background:rgba(0, 0, 0, 0); + -webkit-border-radius:0px 0px 0px 0px; + -moz-border-radius:0px 0px 0px 0px; + -ms-border-radius:0px 0px 0px 0px; + -o-border-radius:0px 0px 0px 0px; + border-radius:0px 0px 0px 0px; + font-family:inherit; + font-size:14px; +} +/* end new header */ +@media (min-width: 1320px) { + .body .flowListDiv dl.flowList { + -webkit-column-count:3; + -moz-column-count:3; + column-count:3 + } +} +@media (min-width: 1120px) { + #navbar.fixed { + -moz-box-shadow:0px 0px 8px rgba(0,0,0,0.23); + -webkit-box-shadow:0px 0px 8px rgba(0,0,0,0.23); + box-shadow:0px 0px 8px rgba(0,0,0,0.23) + } + #navbar.fixed #mm-wrap #mm-helper > li.mm-item > a.mm-link { + height:50px; + line-height:50px + } + #navbar.fixed .navbar-oneQt:before { + font-size:35px; + top:7px + } + + .flowListDiv dl.flowList { + -webkit-column-count:2; + -moz-column-count:2; + column-count:2 + } +} +@media (max-width: 1120px) { + #navbar { + padding:0; + position:relative + } + #navbar .navbar-oneQt:before { + left:10px + } + #navbar .container { + max-width:100%; + padding:0 + } + #footerbar .container { + padding:0 + } + body .main { + margin-top:0px + } + #footerbar .footer-main .footer-nav { + padding:3.9% 0 3.9% 3%; + border-bottom:1px solid #413d3b; + float:none; + display:block; + width:auto + } + #footerbar .footer-main .theqtcompany { + clear:both; + float:left; + margin:30px 0 8px 3% + } + #footerbar .footer-main .footer-social { + float:left; + padding:50px 0px 0px 3% + } + #footerbar #menu-footer-submenu { + clear:both; + float:none; + display:block; + padding:0px 0px 3.9% 3% + } + ul#menu-footer-submenu { + margin-left: 0 + } +} +.cookies_yum { + background-color:#cecfd5; + display:none; + width:100% +} +.cookies_yum img { + width:25px; + top:6px; + display:inline-block; + position:absolute; + left:13px +} +.cookies_yum div { + margin:0 auto; + max-width:1280px; + min-height:30px; + padding:6px 0px 6px 0px; + position:relative +} +.cookies_yum p { + color:#09102b; + margin:0px; + font-size:0.79em; + display:inline-block; + line-height:1.2; + padding:0 30px 0 50px +} +.cookies_yum p a { + white-space:nowrap +} +.cookies_yum a:hover { + color:#46a2da +} +.cookies_yum .close { + width:15px; + height:15px; + background-image:url("cookiebar-x.png"); + background-size:15px 30px; + background-position:top left; + cursor:pointer; + top:13px; + right:13px; + position:absolute; + transition:none +} +.cookies_yum .close:hover { + background-position:bottom left +} +#sidebar-toggle,#toc-toggle { + width:24px; + height:14px; + background-size:24px 28px; + cursor:pointer; + background-image:url("list_expand.png"); + float:right +} +#sidebar-toggle.collapsed, +#toc-toggle.collapsed { + background-position:bottom left +} +#sidebar-content > h2 { + display:none +} +#footerbar { + background:#222840; + color:#fff; + font-size: 0.9em; +} +#footerbar.fixed { + bottom:0; + left:0; + width:100% +} +#footerbar .footer-nav { + display:inline; + float:left +} +#footerbar .footer-main .footer-nav li { + float:left; + margin-right:1em +} +#footerbar .footer-main .footer-nav li a { + display:block; + padding:30px 0 10px 0; + line-height:20px; + height:20px; + color:#fff; + font-weight: 600; +} +#footerbar .footer-main .footer-nav li a:hover,#footerbar .footer-main .footer-nav li.current-menu-item a { + color:#eee +} +#footerbar .footer-main .footer-nav .sub-menu { + margin-left:0; + margin-bottom:0 +} +#footerbar .footer-main .footer-nav .sub-menu li { + float:none; + width: 100%; +} +#footerbar .footer-main .footer-nav .sub-menu ul { + padding:1px 1em; + font-size:0.786em; + line-height:8px; + float:none; + color:#5d5b59; + margin-bottom:0 +} +#footerbar .footer-main .footer-nav .sub-menu li a { + padding:2px 0; + font-size:1em; + float:none; + color:#cecfd5; + font-weight: 400; +} +#footerbar .footer-main .footer-nav .sub-menu li a:hover,#footerbar .footer-main .footer-nav .sub-menu li.current-menu-item a { + color:#eee +} +#footerbar .theqtcompany { + background:url("theqtcompany.png") no-repeat; + background-size:100%; + width:215px; + height:68px; + display:inline; + float:right; + margin:29px 0 28px 30px +} +#footerbar .footer-social { + display:inline; + float:right; + width:164px +} +#footerbar .footer-main .footer-social>div { + margin-left:0.1em; + margin-bottom:10px +} +#footerbar .disclaimer { + font-size:0.786em; + line-height:2.73; + color:#868584; + padding-top:20px; + padding-bottom:0.5% +} +#footerbar .disclaimer a { + color:#bdbebf +} +#footerbar .disclaimer a:hover { + color:#d6d6d6 +} +#footerbar .disclaimer ul li { + float:left; + vertical-align:middle; + margin-left:1.18em +} +#footerbar .disclaimer ul li:first-child { + margin-left:0 +} +#footerbar .disclaimer ul.lang-selector a { + color:#506a34; + color:rgba(128,195,66,0.3) +} +#footerbar .disclaimer ul.lang-selector a:hover { + color:#80c342; + color:rgba(128,195,66,0.7) +} +#menu-footer-menu, #menu-footer-menu ul { + margin-left:0; + margin-bottom:0 +} +@font-face { + font-family: 'Titillium Web'; + font-style: normal; + font-weight: 400; + src: url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.eot"); + /* IE9 Compat Modes */ + src: local("Titillium Web"), local("TitilliumWeb-Regular"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.eot?#iefix") format("embedded-opentype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.woff2") format("woff2"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.woff") format("woff"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.ttf") format("truetype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.svg#TitilliumWeb") format("svg"); + /* Legacy iOS */ +} +/* titillium-web-italic - latin_latin-ext */ +@font-face { + font-family: 'Titillium Web'; + font-style: italic; + font-weight: 400; + src: url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.eot"); + /* IE9 Compat Modes */ + src: local("Titillium WebItalic"), local("TitilliumWeb-Italic"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.eot?#iefix") format("embedded-opentype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.woff2") format("woff2"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.woff") format("woff"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.ttf") format("truetype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.svg#TitilliumWeb") format("svg"); + /* Legacy iOS */ +} +/* titillium-web-600 - latin_latin-ext */ +@font-face { + font-family: 'Titillium Web'; + font-style: normal; + font-weight: 600; + src: url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.eot"); + /* IE9 Compat Modes */ + src: local("Titillium WebSemiBold"), local("TitilliumWeb-SemiBold"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.eot?#iefix") format("embedded-opentype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.woff2") format("woff2"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.woff") format("woff"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.ttf") format("truetype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.svg#TitilliumWeb") format("svg"); + /* Legacy iOS */ +} +@font-face { + font-family:'Droid Sans Mono'; + font-style:normal; + font-weight:400; + src:local("Droid Sans Mono"),local("DroidSansMono"),url(//fonts.gstatic.com/s/droidsansmono/v7/ns-m2xQYezAtqh7ai59hJUYuTAAIFFn5GTWtryCmBQ4.woff) format("woff") +} +@font-face { + font-family:'Qt Icons'; + src:url("../style/icomoon.eot?-tgjuoj"); + src:url("../style/icomoon.eot?#iefix-tgjuoj") format("embedded-opentype"),url("../style/icomoon.woff?-tgjuoj") format("woff"),url("../style/icomoon.ttf?-tgjuoj") format("truetype"),url("../style/icomoon.svg?-tgjuoj#icomoon") format("svg"); + font-weight:normal; + font-style:normal +} +@font-face { + font-family:'social-icons'; + src:url("../style/social-icons.eot?54625607"); + src:url("../style/social-icons.eot?54625607#iefix") format("embedded-opentype"), + url("../style/social-icons.woff?54625607") format("woff"); + font-weight:normal; + font-style:normal +} +.clearfix:before,.clearfix:after { + content:" "; + display:table +} +.clearfix:after { + clear:both +} +.clearfix { + *zoom:1 +} +.clearfix .right { + float:right +} +html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,img,ins,kbd,q,s,samp,small,strike,strong,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td,article,aside,canvas,details,embed,figure,figcaption,footer,header,hgroup,menu,nav,output,ruby,section,summary,time,mark,audio,video { + margin:0; + padding:0; + border:0; + font-size:100% + line-height: 1.4; +} +html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,img,ins,kbd,q,s,samp,small,strike,strong,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,caption,article,aside,canvas,details,embed,figure,figcaption,footer,header,hgroup,menu,nav,output,ruby,section,summary,time,mark,audio,video { + vertical-align:baseline +} +h1,h2,h3,h4,h5,h6 { + font-weight:300 +} +.body h2,.body h3,.body h4,.body h5,.body h6 { + margin:1.5em 0 0.75em +} +.body h1 { + margin-bottom:0.75em; + font-size:2.25em; +} +.body h3.fn,.body h3.flags { + color:#26282a; + font-size:1.46em; + padding:15px 0 15px 0; + border-bottom:2px #eee solid; + word-wrap:break-word +} +.body .fngroup { + border-bottom:2px #eee solid; + padding-bottom:15px; + margin-bottom:1.5em +} +.body .fngroup h3.fngroupitem { + margin:0; + padding-bottom:0; + border:none +} +.body h3.fn .name, +.body h3 span.type, +.qmlname span.name { + font-weight: 400 +} +.qmlname { + font-size:1.46em +} +.qmlproto table { + border:none; + border-bottom:2px #eee solid +} +.qmlproto table p { + max-width:100% +} +.qmlproto table tr { + background-color:#fff +} +.qmlname td, .qmlname th { + border:none; + text-align:left; + padding:5px 0 0 0 +} +.qmlreadonly,.qmldefault { + padding:0 5px 0 5px; + font-size:0.75em; + background-color:#eee; + float:right +} +.qmlreadonly { + color:#414141 +} +.qmldefault { + color:#D14141 +} +.rightAlign { + padding:3px 5px 3px 10px; + text-align:right +} +.centerAlign.functionIndex { + text-align:center; + font-size:150%; + margin-bottom: 1em +} +article,aside,details,figcaption,figure,footer,header,hgroup,menu,nav,section { + display:block +} +body { + line-height:1; + font-family:'Titillium Web', Arial, Helvetica, sans-serif; + font-weight:400; + transition-duration:1s; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + font-size: 16px; + background-color:#f3f3f4; + color:#404244; +} +ol,ul { + list-style-type: square; + color: #17a81a; +} +.body ol,.body ul { + margin-top:0.75em; + margin-left:20px +} +.bodywrapper ol>li { + list-style-type:decimal; + margin-left:15px +} +.bodywrapper ol.a >li { + list-style-type:lower-alpha; +} +.bodywrapper ol.A >li { + list-style-type:upper-alpha; +} +.bodywrapper ol.i >li { + list-style-type:lower-roman; +} +.bodywrapper ol.I >li { + list-style-type:upper-roman; +} +.body li p { + margin-top:1em +} +blockquote,q { + quotes:none; + border-left:10px solid #ddd; + padding-left:10px +} +blockquote:before,blockquote:after,q:before,q:after { + content:''; + content:none; + width:100% +} +table { + border-collapse:collapse; + border-spacing:0; + margin-bottom:5px; + width:100% +} +a { + color:#17a81a; + text-decoration:none; + transition-duration:0.3s +} +a:hover { + color:#17a81a +} +.main,#footerbar>div { + max-width:1280px; + width:95%; + margin:0 auto +} +.main { + margin-top:80px +} +@media (max-width: 1120px) { + .main,.navbar-header,#footerbar>div { + width: 100%; + margin: 0; + } + .main .main-rounded { + padding: 0 15px; + } +} +.main_index { + background-color:#fff +} +.sectionlist { + margin-bottom:2em +} +[class*="col-"] { + letter-spacing:normal +} +.landing,.main_index .row { + letter-spacing:-0.31em +} +.main_index .row>div { + letter-spacing:normal +} +.col-1,.body { + display:inline-block; + background-color:#fff; + padding: 25px 35px 20px 30px; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box; +} +.col-1 h2 { + font-size:1.8em; + font-weight:300; + line-height:1.1; + margin-bottom:0.83em; + margin-top:1em +} +.icons1of3 img { + display:inline-block; + float:left; + margin-right:0.75em; + margin-top:-5px; + width:2.75em +} +div.multi-column { + position:relative +} +div.multi-column div { + display:-moz-inline-box; + display:inline-block; + vertical-align:top; + margin-top:1em; + margin-right:2em; + width:16em +} +.sidebar { + display:block; + position:relative; + position:sticky; + float:left; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box; + width:20%; + padding-right:20px +} +.sidebar li { + text-overflow:ellipsis; + overflow:hidden +} +.toc,.sectionlist { + padding:25px; + background-color:#fff; + margin-bottom:1.25em +} +.sidebar .sectionlist p { + margin-bottom:0 +} +.sectionlist.promo { + padding:0; + background-color:#f3f3f4 +} +.sidebar-content:empty { + display:none; + visibility:hidden +} +.col-2 h2,.toc h3,.sidebar-content h2, +.sidebar-content h3,.sectionlist h2, +.sphinxsidebar { + position: -webkit-sticky; + position: sticky; + top: 64px; + overflow: scroll; + overflow-x: hidden; + overflow-y: hidden; +} +.sphinxsidebar h3 { + font-weight: bold; + margin-bottom:1em; +} +.toc h3 a { + color:#404244 +} +.title { + font-size:2.25em; + font-weight:300; + letter-spacing:-1px; + line-height:1.15em; + margin-bottom:0.5em; + word-wrap:break-word +} +.navigationbar,col-1 h2 { + font-size:0.85em +} +.navigationbar h1 { + font-size:2.5em; + margin-bottom:0.85em; + margin-top:0.85em +} +.navigationbar li { + display:inline-block; + margin-right:5px; + position:relative; + padding-right:10px; + color:#585a5c +} +.navigationbar ul:last-of-type li a { + color:#404244 +} +.sectionlist li, .sphinxsidebar li { + padding-bottom: 10px; + line-height: 1.75em; +} +.col-1 ul { + margin-bottom:1.56em +} +.bodywrapper li { + margin-top:0.5em; + line-height:1.25em +} +.bodywrapper li.level2 { + margin-left:10px; + margin-top:0.4em; + font-size:0.9375em; +} +.bodywrapper p, +.bodywrapper dd { + line-height:1.25em; + margin:1em 0 1em; + color:#404244 +} +.bodywrapper b { + font-weight:600 +} +.body ul,.body ol { + /* margin-bottom:1.5em */ +} +.bodywrapper ul ul { + margin-top:0.5em +} +.bodywrapper .naviNextPrevious { + margin-top:25px; + max-width:100% +} +.naviNextPrevious.headerNavi, +p.naviNextPrevious + p { + display:none +} +.nextPage { + float:right +} +.prevPage:before { + content:"< " +} +.nextPage:after { + content:" >" +} +.navigationbar li a { + color:#404244 +} +.navigationbar li:after { + color:#404244; + content:"›"; + display:inline-block; + font-size:1.5em; + line-height:1; + position:absolute; + right:-2px; + top:-4px +} +.sub-navigation { + margin-top:10px +} +.navigationbar li:last-child:after,.sub-navigation li:after { + content:none +} +.navigationbar { + margin-bottom:10px; + line-height:1em +} +#buildversion { + margin-bottom:10px; + font-style:italic; + font-size:small; + float:right +} +.copy-notice { + width:75%; + font-size:0.75em; + margin:20px 35px 0 10px; + line-height:1.75em; + float:right; + color:#585a5c +} +.copy-notice.index { + margin-top:10px; + float:none +} +li a.active { + color:#585a5c +} +.flowList { + padding:25px +} +.flowListDiv dl { + -webkit-column-count:1; + -moz-column-count:1; + column-count:1 +} +.flowList dd { + display:inline-block; + margin-left:10px; + width:90%; + line-height:1.15em; + overflow-x:hidden; + text-overflow:ellipsis +} +.alphaChar { + font-size:2em; + position:absolute +} +.flowList.odd { + background-color:#f9f9f9 +} +.body ul>li,.doc-column ul>li { + list-style-image:url("list_arrow.png"); + margin-left:15px; + color:#404244; + margin-top:0.65em; + line-height:1em +} +.bodywrapper table p { + margin:0px; + padding:0px +} +.bodywrapper table p { + margin:0px; + padding:0px; + min-height:1.25em +} +.bodywrapper .qmldoc { + margin-top:0.75em +} +.body h2 { + margin-top: 1.5em; + font-size:1.75em +} +.body h3 { + font-size:1.35em +} +.body h4 { + font-size:1.15em +} +.body p img { + margin-top:0.75em; + max-width:100% +} +.body .border img { + box-shadow:3px 3px 8px 3px rgba(200,200,200,0.5) +} +.body .border .player { + box-shadow:3px 3px 8px 3px rgba(200,200,200,0.5) +} +.body p.figCaption { + transform:translateY(-30px); + color:#606366; + font-size:95%; + margin-left:3px; + font-style:italic +} +.body table { + width:initial; + vertical-align:initial +} +table .odd { + background-color:#f9f9f9 +} +table thead { + text-align:left; + padding-left:20px +} +table,table td,table th { + border:1px solid #eee +} +table td,table th { + padding:5px 20px; + line-height:1.3 +} +.body .fixed table td { + min-width:50%; + width:50% +} +table.alignedsummary,table.propsummary { + width:initial +} +table.valuelist td.tblval { + font-size:0.75em +} +div.main_index .row { + border-bottom:10px solid #f3f3f4 +} +div.main_index .row { + position:relative +} +div.main_index .row>div { + display:inline-block; + width:50%; + vertical-align:top; + padding:2em 3em; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box +} +div.main_index h2 { + font-size:2.1875em; + margin-bottom:1em +} +#search_bar { + width:40%; + float:right +} +div.main_index .row:after { + content:""; + position:absolute; + top:0; + right:50%; + height:100%; + width:10px; + background-color:#f3f3f4 +} +div.table { + overflow-x:auto +} +.body tr > td > pre { + font-size:0.75em +} +p.qt_commercial { + border:3px solid #5caa15; + margin:0 auto; + padding:15px; + width:28%; + text-align:center; + clear:both +} +h1.qt_commercial { + padding:20px; + background-color:#5caa15; + display:inline; + float:right; + font-size:1.25em; + line-height:1.25em; + height:1.25em; + color:#fff +} +div.qt_commercial { + border-top:5px solid #5caa15; + margin-bottom:50px +} +div.pre { + position:relative; + height:auto +} +pre, .LegaleseLeft { + background-color:#222840; + color:#fff; + display:block; + font-family:"Droid Sans Mono"; + line-height:1.5; + overflow-x:auto; + margin-bottom:25px; + padding:25px; + margin-top:0.75em; + font-size: .8em; +} +.bodywrapper .LegaleseLeft p { + color:#fff; + white-space: pre-wrap +} +pre .str,code .str { + color:#aaaaaa +} +pre .kwd,code .kwd { + color:#ffff55 +} +pre .com,code .com { + color:#55ffff +} +pre .typ,code .typ { + color:#4f9d08 +} +pre a .typ,code a .typ { + color:#21be2b +} +pre .lit,code .lit { + color:#ff55ff +} +pre .pun,code .pun { + color:#fff +} +pre .pln,code .pln { + color:#fff +} +@media print { + pre { + background-color:#eee !important + } + pre .str,code .str { + color:#060 + } + pre .kwd,code .kwd{ + color:#006; + font-weight:bold + } + pre .com,code .com { + color:#600 + } + pre .typ,code .typ { + color:#404; + font-weight:bold + } + pre .lit,code .lit { + color:#044 + } + pre .pun,code .pun { + color:#440 + } + pre .pln,code .pln { + color:#000 + } +} +pre.wrap { + white-space:pre-wrap +} +pre span.wrap { + display:none; + background:url("wrap.png") no-repeat; + right:0; + top:2px; + position:absolute; + width:20px; + height:14px; + margin:4px; + opacity:0.65 +} + +span.pre { + color: #09102d; +} + +span.wrap:hover { + opacity:1 +} +span.wrap:active { + opacity:0.75 +} +.copy_text { + background-color:#46a2da; + color:#fff; + border:2px solid #46a2da; + padding:10px 16px; + margin-left:-10px; + margin-top:-50px; + position:absolute; + opacity:0; + cursor:pointer; + float:right +} +.copy_text:hover { + background-color:#fff; + color:#46a2da +} +code,.codelike { + font-family:"Droid Sans Mono" +} +#detailed-description .function dt > code, +#detailed-description .function dt > em { + font-weight:bold +} +h3.fn code { + font-size:0.75em; + float:right; + background-color:#eee; + padding:3px; + margin: 3px 0 0 20px +} +pre:hover>.copy_text { + display:inline-block; + opacity:1; + transition:0.5s ease +} +#main_title_bar { + background:url("pyside-logo.png") no-repeat; + background-size:100%; + width:366px; + height:86px; + margin:15px 0 15px 0 +} +#main_title_bar h1 { + visibility:hidden +} +#main_title_bar .search_bar { + letter-spacing:normal; + width:50%; + display:inline-block; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box; + vertical-align:middle +} +#main_title_bar h1 { + letter-spacing:normal; + display:inline-block; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box; + vertical-align:middle +} +#main_title_bar .search_bar * { + letter-spacing:normal; + padding:0; + margin:0; + border:none +} +#sidebar-toggle,#toc-toggle { + display:none +} +@media (max-width: 980px) { + body { + font-size:calc-em(14px) + } + #main_title_bar>h1,#main_title_bar .search_bar { + width:100% + } + #main_title_bar .search_bar { + margin-bottom:15px + } + .main { + margin-top:0px + } + .main_index .row { + border:none !important + } + .title { + font-size:1.5em; + font-weight:400; + word-wrap:break-word + } + .col-1,.body,.naviNextPrevious,.sidebar { + padding:10px + } + .sidebar { + position:relative; + padding-top:0 + } + .search .sidebar { + display:none; + visibility:hidden + } + .col-2 h2,.toc h3,.sidebar-content h2,.sidebar-content h3,.sectionlist h2 { + text-align:center; + margin-bottom:5px + } + div.main_index .row:after { + content:none + } + div.main_index .row>div { + display:block !important; + width:100%; + padding:15px; + margin:0 + } + .body,.sidebar,.col-1 { + width:100% + } + .sidebar-content,.col-2,.toc { + background-color:#fff; + margin-bottom:1em; + padding:20px + } + #sidebar-toggle,#toc-toggle { + display:block + } + #sidebar-toggle.collapsed + h2 { + display:block + } + .bodywrapper p { + margin-bottom:1em; + max-width:100% + } + table td,table th { + padding:5px 5px + } + .sectionlist { + padding:0 + } + .sidebar > .sectionlist { + padding:20px + } + .sectionlist.promo { + max-width:46%; + margin:0 auto 1em auto; + float:left; + padding:0 2% + } + .sidebar .sidebar-content { + clear:both + } + .copy-notice { + float:none; + width:initial + } +} +[id]:target > *:first-child, +dt[id]:target { + -webkit-animation:highlighter 3s; + animation:highlighter 3s +} +@-webkit-keyframes highlighter { + 25% { + background-color:#d1e8f6; + color:#444 + } + 75% { + background-color:#d1e8f6; + color:#444 + } +} +@keyframes highlighter { + 25% { + background-color:#d1e8f6; + color:#444 + } + 75% { + background-color:#d1e8f6; + color:#444 + } +} +@-webkit-keyframes copypaste { + 25% { + opacity:1 + } + 100% { + border-radius:10px; + margin-top:-50px; + opacity:1 + } +} +@keyframes copypaste { + 25% { + opacity:1 + } + 100% { + border-radius:10px; + margin-top:-50px; + opacity:1 + } +} +#footer { + clear:both +} +.footer-social i { + font-family: "social-icons"; + font-style: normal; + font-size:150%; + margin: .55em; + color: #cecfd5 +} +.footer-social i:hover { + color: #eee +} +.footer-social .icon-twitter:before { + content: '\f099' +} +.footer-social .icon-facebook:before { + content: '\f09a' +} +.footer-social .icon-youtube:before { + content: '\f16a' +} +.menuextraslanguages { + display:none; + visibility:hidden +} +form.gsc-search-box { + font-size: 25px !important; + margin-top: 0 !important; + margin-right: 0 !important; + margin-bottom: 4px !important; + margin-left: 0 !important; + width: 102.5% !important; +} +table.gsc-search-box { + border-style: none !important; + border-width: 0 !important; + border-spacing: 0 0 !important; + width: 100% !important; + margin-bottom: 2px !important; +} + +table.gsc-search-box td { + vertical-align: middle !important; +} + +table.gsc-search-box td.gsc-input { + padding-right: 0px !important; +} +table.gsc-search-box td.gsc-input input { + background-position: 10px center !important; +} + +td.gsc-search-button { + width: 1% !important; +} + +td.gsc-clear-button { + width: 14px !important; + visibility:hidden !important; + display:none !important; +} +table.gsc-branding td, +table.gsc-branding { + margin: 0 0 0 0 !important; + padding: 0 0 0 0 !important; + border: none !important; +} + +table.gsc-branding { + border-style: none !important; + border-width: 0 !important; + border-spacing: 0 0 !important; + width: 100% !important; +} + +.gsc-branding-text { + color: #676767 !important; +} + +td.gsc-branding-text { + vertical-align: top !important; +} +td.gsc-branding-text div.gsc-branding-text { + padding-bottom: 2px !important; + text-align: right !important; + font-size: 11px !important; + margin-right: 2px !important; +} + +td.gsc-branding-img { + width: 65px !important; + vertical-align: bottom !important; +} + +img.gsc-branding-img { + padding-top: 1px !important; + margin: 0 0 0 0 !important; + padding-right: 0 !important; + padding-left: 0 !important; + padding-bottom: 0 !important; + border: none !important; + display: inline !important; +} + +input.gsc-search-button { + background-color: white !important; + height: 35px !important; + width: 25px !important; + color: transparent !important; + background-image: url("doc_search.png") !important; + background-size: 25px auto; + background-position: 0px 5px; + background-repeat: no-repeat; + margin-left: -43px !important; + overflow: hidden; + min-width: 20px !important; +} + +input.gsc-search-button:hover { + cursor: pointer; +} + +input.gsc-search-button:focus { + outline: none; + box-shadow: none; +} + +.gsc-search-box-tools .gsc-clear-button { + display: none !important; + visibility: none !important; +} + +.gsc-overflow-hidden { + overflow: hidden !important; +} + +input.gsc-input { + background-color: #fff !important; + border: 1px solid #d6d6d6 !important; + box-sizing: border-box !important; + -moz-box-sizing: border-box !important; + color: #868482 !important; + outline: 0 none !important; + padding: 9px 10px 10px !important; + transition: color 0.5s ease 0s, box-shadow 0.5s ease 0s, background-color 0.5s ease 0s !important; +} + +input { + font-family: 'Titillium Web', Arial, Helvetica, sans-serif !important; + line-height: 1.5 !important; + font-weight: 300 !important; + vertical-align:middle +} + +input:focus { + border-color: #46a2da; + box-shadow: 0 0 5px #46a2da; + color: #000; +} + +.animation { + width: 100%; + border-style: none; + border-width: 0 +} + +.player { + width: auto; + position: relative; + display: table; + margin-bottom:1.5em; +} + +.playcontrol { + display: none; + background: url("play_icon.svg") no-repeat center, + linear-gradient( + rgba(0,0,0,0.15), rgba(0,0,0,0.15) + ); + background-size: 25%; + width: 100%; + height: 100%; + position: absolute; + left: 0%; + right: 0%; + top: 0%; + bottom: 0%; + margin: auto +} + +/* expand/collapse code sections */ +pre input { + display:none; + visibility:hidden +} +pre label { + display:block; + margin:-3px 3px 0 -16px; + text-align:center; + color:#21be2b; + float:left; +} +pre label:hover { + color:#fff +} +pre label::before { + font-weight:600; + font-size:16px; + content:"+"; + display:inline-block; + width:16px; + height:16px +} +#ec_expand { + height:16px; + overflow:hidden; + transition:height 0.35s; +} +#ec_expand::before { + content:"...*/"; + color:#aaa; + background-color:#3a4055; + z-index:99 !important; + right:25px; + position:absolute +} +#ec_toggle:checked ~ #ec_expand { + height:initial +} +#ec_toggle:checked ~ #ec_expand::before { + content:"" +} +#ec_toggle:checked ~ label::before { + content:"-" +} + +/* permalinks */ +h1:hover > .headerlink, +h2:hover > .plink, +h2:hover > .headerlink, +h3:hover > .plink, +h3:hover > .headerlink, +h4:hover > .plink, +h4:hover > .headerlink, +h5:hover > .plink, +h5:hover > .headerlink { + opacity:1 +} +a.plink, a.headerlink { + opacity: 0; + padding-left: 8px; + font-size: 0.8em; + font-weight: 600; + transition: opacity 180ms ease-in-out +} +a.plink::before { + content:'\00B6' +} + +table.special { + border: 3px; + padding: 0px; + border-collapse: separate; + border-spacing: 20px; + line-height: 1.5em; +} + +.special p { + text-align: center; + color: #3a4055; +} + +.special a { + display: block; + border-bottom: 0; + text-decoration: none; +} + +.special a:hover { + border-bottom: 0; + text-decoration: none; +} + +.special strong { + color: #17a81a; + font-size: 110%; + font-weight: normal; +} + +table.special th, +table.special td { + border: 1px solid #888; + padding-top: 14px; + padding-bottom: 14px; + padding-left: 6px; + padding-right: 5px; + border-radius: 5px; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; +} + +.special td:hover { + padding-top: 2px; + padding-bottom: 2px; + border-bottom: 4px solid #41cd52; +} diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/pysidelogo.png b/sources/shiboken6/doc/_themes/pysidedocs/static/pysidelogo.png Binary files differnew file mode 100644 index 000000000..3a2f2bd17 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/static/pysidelogo.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/relbar_bg.png b/sources/shiboken6/doc/_themes/pysidedocs/static/relbar_bg.png Binary files differnew file mode 100644 index 000000000..4036733a7 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/static/relbar_bg.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs/theme.conf b/sources/shiboken6/doc/_themes/pysidedocs/theme.conf new file mode 100644 index 000000000..01a4dd4a1 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = default +stylesheet = pyside.css +pygments_style = none + +[options] +nosidebar = false diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/domainindex.html b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/domainindex.html new file mode 100644 index 000000000..c136cdd1c --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/domainindex.html @@ -0,0 +1,57 @@ +{# + basic/domainindex.html + ~~~~~~~~~~~~~~~~~~~~~~ + + Template for domain indices (module index, ...). + + :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{% extends "layout.html" %} +{% set title = indextitle %} +{% block extrahead %} +{{ super() }} +{% if not embedded and collapse_index %} + <script type="text/javascript"> + DOCUMENTATION_OPTIONS.COLLAPSE_INDEX = true; + </script> +{% endif %} +{% endblock %} +{% block body %} +<div class="section"> + {%- set curr_group = 0 %} + + <h1>{{ indextitle }}</h1> + + <div class="modindex-jumpbox"> + {%- for (letter, entries) in content %} + <a href="#cap-{{ letter }}"><strong>{{ letter }}</strong></a> + {%- if not loop.last %} | {% endif %} + {%- endfor %} + </div> + + <table class="indextable modindextable" cellspacing="0" cellpadding="2"> + {%- for letter, entries in content %} + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap"><td></td><td><a name="cap-{{ letter }}"> + <strong>{{ letter }}</strong></a></td><td></td></tr> + {%- for (name, grouptype, page, anchor, extra, qualifier, description) + in entries %} + {%- if grouptype == 1 %}{% set curr_group = curr_group + 1 %}{% endif %} + <tr{% if grouptype == 2 %} class="cg-{{ curr_group }}"{% endif %}> + <td>{% if grouptype == 1 -%} + <img src="{{ pathto('_static/minus.png', 1) }}" id="toggle-{{ curr_group }}" + class="toggler" style="display: none" alt="-" /> + {%- endif %}</td> + <td>{% if grouptype == 2 %} {% endif %} + {% if page %}<a href="{{ pathto(page) }}#{{ anchor }}">{% endif -%} + <tt class="xref">{{ name|e }}</tt> + {%- if page %}</a>{% endif %} + {%- if extra %} <em>({{ extra|e }})</em>{% endif -%} + </td><td>{% if qualifier %}<strong>{{ qualifier|e }}:</strong>{% endif %} + <em>{{ description|e }}</em></td></tr> + {%- endfor %} + {%- endfor %} + </table> +</div> +{% endblock %} diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/fakebar.png b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/fakebar.png Binary files differnew file mode 100644 index 000000000..b45830e00 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/fakebar.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/logo_python.jpg b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/logo_python.jpg Binary files differnew file mode 100644 index 000000000..cd474efba --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/logo_python.jpg diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/logo_qt.png b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/logo_qt.png Binary files differnew file mode 100644 index 000000000..3bc03b7c7 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/logo_qt.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/minus.png b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/minus.png Binary files differnew file mode 100644 index 000000000..da1c5620d --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/minus.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/plus.png b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/plus.png Binary files differnew file mode 100644 index 000000000..b3cb37425 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/plus.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/pyside.css b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/pyside.css new file mode 100644 index 000000000..aee5e4420 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/pyside.css @@ -0,0 +1,1943 @@ +@import url('cookie-confirm.css') screen; + +/* -- admonitions -- */ + +div.admonition { + margin: 1.5em 0 1.5em; + padding: 0; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.admonition code { + font-family: inherit; +} + +p.admonition-title + p { + padding-left: 1em; +} + +div.admonition a:after { + content: ', '; +} + +div.admonition a:last-child:after { + content: ''; +} + +.body { + width: 100% +} +.bodywrapper .admonition p.admonition-title { + margin-bottom:5px +} + +.bodywrapper .admonition p { + margin:0 +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +div.warning, div.seealso, div.note { + padding: 6px 0px 6px 10px; + border: none; +} + +div.warning { + background-color: #ffe4e4; +} + +div.seealso { + background-color: #fff2d6; +} + +div.note { + background-color: #f3f3f4; +} + +table.docutils { + margin-right: auto; + margin-bottom: 10px; + border: none; + width: initial; +} + +table.docutils.colwidths-given td { + float: none; +} + +table.docutils th, +table.docutils td { + padding-left:0; + border: none; +} + +table.docutils td ul { + margin:0 +} + +table.docutils td ul > li { + margin: 0 0 0.5em; +} +h2 em { + float: right; + font-size: 10px; + position: relative; + top: -20px; +} + +.document { + padding-bottom: 20px; +} + +.documentwrapper { + margin-left: 20px; +} + +.body blockquote { + border: none; + padding-left: 0; + margin-bottom: 1.5em; +} + +.sphinxsidebar { + float: left; + width: 186px; + padding: 25px; + text-align: left; + background-color: #fff; +} + +.sphinxsidebar ul { + padding: 0px; + margin: 0px; + list-style-position: inside; +} + +.sphinxsidebar > ul { + padding: 0px; + margin: 0px; +} + +.sphinxsidebar ul li li { + margin-left: 10px; + padding: 0px; + font-size: 0.95em; +} + +.sphinxsidebar ul a, +.sphinxsidebar p.topless a { + word-break: break-word; +} + +.sphinxsidebar h3, .sphinxsidebar h3 a { + color: #333; +} + +.sphinxsidebar p.topless { + margin: 1em 0 1em; +} + +.pysidetoc ul { + list-style: none; + padding: 0px; + margin: 0px; +} + +.pysidetoc em { + font-style: normal; +} + +.pysidetoc strong { + display: block; + padding: 5px; + margin: 0 10px 10px 0; + border: none; + background-color: #e2e2e2; +} + +.section .docutils.container td { + float:left; +} + +.hide { + display: none; +} + +/* copy-notice */ +.document + p { + margin-left: 255px; + width: 70%; + font-size: 0.75em; + margin: 0 35px 15px 280px; +} + +#searchbox { + border-top: 1px solid #989898; + padding-top: 10px; + margin-left: -10px; + margin-right: -10px; + padding-left: 10px; + padding-right: 10px; +} + +#search_button { + border: 1px solid #3A393A; + background-color: #3A393A; + color: white; + cursor: pointer; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + +} + +form { + margin: 0px; + padding: 0px; +} + +#searchbox h3 { + padding: 10px 0 0 0; + margin-bottom: 5px; +} + +/* search field */ +form #q { + width: 136px; + /* height: 22px; */ + /* border: none; */ + margin: 0px; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + margin-top: 2px; + padding: 4px; + line-height: 22px; +} + +#search-results h2 { + display: none; +} + +#search-results h2 { + display: none; +} + +#search-results ul.search { + margin: 0px; + padding: 0px; +} + +ul.search div.context { + padding-left: 40px; +} + +#installation td { + text-align: center; + font-weight: bold; +} + +em { + color: inherit; + font-style:italic; +} + +/******** REL bar *********/ + +.related { + display: inline; +} + +.related h3 { + display: none; +} + +.align-center { + text-align: center; +} + +.contentstable { + width: 100%; +} + +.contentstable td { + padding-left: 30px; + vertical-align: top; +} + +p.biglink a { + font-size: 20px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +p.highlight-link { + margin-top: 10px; + font-size: 0.8em; +} + +#synopsis table, table.field-list { + margin: 1em 0 1em 0; +} + +table.field-list tr { + text-align: left; +} + +tt.descname { + font-size: 120%; + font-weight: bold; +} + +#functions ul, #virtual-functions ul, #slots ul, #signals ul, #static-functions ul { + margin: 0; + padding: 6px; + border: 1px solid #ddd; + border-radius: 0; + background-color: #e2e2e2; +} + +#functions p, #virtual-functions p, #slots p, #signals p, #static-functions p { + margin: 0; + padding: 0; +} + +#functions li, #virtual-functions li, #slots li, #signals li, #static-functions li { + list-style: none; + margin: 5px; + padding: 0; + font-size: 90%; +} + +#synopsis span.pre { + color: #009491; + font-weight: bolder; +} + +#detailed-description .class dt, +#detailed-description .method dt, +#detailed-description .staticmethod dt, +#detailed-description .attribute dt { + margin: 0px; + margin-bottom: 10px; + padding: 10px; + font-weight: bold; + background-color: #e2e2e2; + border: none; + border-radius: 0; +} + +#detailed-description dd > blockquote, +#detailed-description dd > .field-list { + font-family: monospace; + font-size: small; + border-left: 10px solid #e2e2e2; + padding-left: 10px; + margin-bottom: 1.5em; +} + +#detailed-description dd > blockquote blockquote { + border: none; + padding: 0; +} + +#detailed-description .class .field-odd, +#detailed-description .method .field-odd, +#detailed-description .staticmethod .field-odd, +#detailed-description .attribute .field-odd { + margin: 0; + padding: 1px 0 0 0; + background-color: #ffffff; + +} + +#detailed-description .class .field-even, +#detailed-description .method .field-even, +#detailed-description .staticmethod .field-even, +#detailed-description .attribute .field-even { + margin: 0; + padding: 1px 0 0 0; + background-color: #ffffff; +} + +#detailed-description .class .field-odd li, +#detailed-description .method .field-odd li, +#detailed-description .staticmethod .field-odd li, +#detailed-description .attribute .field-odd li { + list-style: none; + margin: 0; + padding: 0; + +} + +#detailed-description .class .field-even li, +#detailed-description .method .field-even li, +#detailed-description .staticmethod .field-even li, +#detailed-description .attribute .field-even li { + list-style: none; + margin: 0; + padding: 0; +} + +#detailed-description .class .field-odd p, +#detailed-description .method .field-odd p, +#detailed-description .staticmethod .field-odd p, +#detailed-description .attribute .field-odd p{ + margin: 0; + margin-left: 20px; + +} + +#detailed-description .class .field-even p, +#detailed-description .method .field-even p, +#detailed-description .staticmethod .field-even p, +#detailed-description .attribute .field-even p{ + margin: 0; + margin-left: 20px; +} + +#detailed-description .class .field-odd p:last-child, +#detailed-description .method .field-odd p:last-child, +#detailed-description .staticmethod .field-odd p:last-child, +#detailed-description .attribute .field-odd p:last-child { + margin-bottom: 10px; + +} + +#detailed-description .class .field-even p:last-child, +#detailed-description .method .field-even p:last-child, +#detailed-description .staticmethod .field-even p:last-child, +#detailed-description .attribute .field-even p:last-child{ + margin-bottom: 10px; +} + +.document dl.attribute, +.document dl.class, +.document dl.method, +.document dl.staticmethod { + margin-top: 2em; +} + +.document dl.attribute dd, +.document dl.class dd, +.document dl.method dd, +.document dl.staticmethod dd { + padding-left: 1em; +} + +#detailed-description .attribute td:nth-child(1) { + font-family: monospace; +} + +/* Qt theme */ +#navbar { + position:fixed; + top:0; + left:0; + z-index:100; + background:#fff; + width:100% +} +#navbar .container, .fixed .container { + max-width:1280px; + margin:0 auto; + padding:0 3.9%; /* 0? */ + position:relative; + overflow:visible +} +#navbar .navbar-header { + position:relative +} +#menuextras li a:hover span { + color: #41cd52; +} +/* new header */ +#mm-wrap, #mm-wrap #mm-helper, +#mm-wrap #mm-helper li.mm-item, +#mm-wrap #mm-helper a.mm-link { + -moz-transition: none; + -o-transition: none; + -webkit-transition: none; + transition: none; + -webkit-border-radius: 0 0 0 0; + -moz-border-radius: 0 0 0 0; + -ms-border-radius: 0 0 0 0; + -o-border-radius: 0 0 0 0; + border-radius: 0 0 0 0; + -webkit-box-shadow: none; + -moz-box-shadow: none; + -ms-box-shadow: none; + -o-box-shadow: none; + box-shadow: none; + background: none; + border: 0; + bottom: auto; + box-sizing: border-box; + clip: auto; + color: #090e21; + display: block; + float: none; + font-family: inherit; + font-size: 14px; + height: auto; + left: auto; + line-height: 1.7; + list-style-type: none; + margin: 0; + min-height: 0; + opacity: 1; + outline: none; + overflow: visible; + padding: 0; + position: relative; + right: auto; + text-align: left; + text-decoration: none; + text-transform: none; + top: auto; + vertical-align: baseline; + visibility: inherit; + width: auto; +} +#mm-wrap #mm-helper { + visibility:visible; + text-align:right; + padding:0 0px 0 0px +} +#navbar #mm-wrap #mm-helper li.mm-item { + border-right:solid #f3f3f4 1px; + padding-right:30px; + padding-left:30px +} +#navbar #mm-wrap #mm-helper li.mm-item > a:hover { + opacity: .5 +} +#mm-wrap #mm-helper > li.mm-item { + margin:0 0 0 0; + display:inline-block; + height:auto; + vertical-align:middle +} +#navbar #mm-wrap #mm-helper li.mm-item:nth-child(3) { + border-right:0 +} +#mm-wrap #mm-helper a.mm-link { + cursor: pointer +} +@media (max-width: 1279px) { + #navbar { + padding:0; + position:relative; + } + #navbar .container { + max-width:100% + } + .container { + padding:0 2% + } +} +#navbar .navbar-oneQt { + display:inline; + float:left; + width:31px; + color:#41cd52 +} +#navbar .navbar-oneQt:before { + content:attr(data-icon); + position:absolute; + top:14px; + left:0; + color:#41cd52; + font-family:'Qt Icons'; + line-height:1; + font-size:40px; + transition:all 0.3s ease-in-out; +} +#mm-wrap { + clear:both; + background:rgba(255, 255, 255, 0.1); + -webkit-border-radius:0px 0px 0px 0px; + -moz-border-radius:0px 0px 0px 0px; + -ms-border-radius:0px 0px 0px 0px; + -o-border-radius:0px 0px 0px 0px; + border-radius:0px 0px 0px 0px +} +#mm-wrap #mm-helper li.mm-item:last-child a { + background:transparent url("icon_avatar.png") 50% 50% no-repeat !important; + background-size:24px !important; + width:24px !important; + height:24px !important; +} +#navbar #mm-wrap #mm-helper li.mm-item > a { + opacity:1; + -webkit-transition:all 0.3s ease-in-out; + -moz-transition:all 0.3s ease-in-out; + -ms-transition:all 0.3s ease-in-out; + -o-transition:all 0.3s ease-in-out; + transition:all 0.3s ease-in-out; +} +#mm-wrap #mm-helper > li.mm-item > a.mm-link { + border-top:0px solid #fff; + border-left:0px solid #fff; + border-right:0px solid #fff; + border-bottom:0px solid #fff; + outline:none; + text-decoration:none; + padding:0 0 0 0; + line-height:70px; + font-weight:normal; + height:70px; + vertical-align:baseline; + text-align:left; + width:auto; + display:block; + color:#090e21; + text-transform:none; + text-decoration:none; + background:rgba(0, 0, 0, 0); + -webkit-border-radius:0px 0px 0px 0px; + -moz-border-radius:0px 0px 0px 0px; + -ms-border-radius:0px 0px 0px 0px; + -o-border-radius:0px 0px 0px 0px; + border-radius:0px 0px 0px 0px; + font-family:inherit; + font-size:14px; +} +/* end new header */ +@media (min-width: 1320px) { + .body .flowListDiv dl.flowList { + -webkit-column-count:3; + -moz-column-count:3; + column-count:3 + } +} +@media (min-width: 1120px) { + #navbar.fixed { + -moz-box-shadow:0px 0px 8px rgba(0,0,0,0.23); + -webkit-box-shadow:0px 0px 8px rgba(0,0,0,0.23); + box-shadow:0px 0px 8px rgba(0,0,0,0.23) + } + #navbar.fixed #mm-wrap #mm-helper > li.mm-item > a.mm-link { + height:50px; + line-height:50px + } + #navbar.fixed .navbar-oneQt:before { + font-size:35px; + top:7px + } + + .flowListDiv dl.flowList { + -webkit-column-count:2; + -moz-column-count:2; + column-count:2 + } +} +@media (max-width: 1120px) { + #navbar { + padding:0; + position:relative + } + #navbar .navbar-oneQt:before { + left:10px + } + #navbar .container { + max-width:100%; + padding:0 + } + #footerbar .container { + padding:0 + } + body .main { + margin-top:0px + } + #footerbar .footer-main .footer-nav { + padding:3.9% 0 3.9% 3%; + border-bottom:1px solid #413d3b; + float:none; + display:block; + width:auto + } + #footerbar .footer-main .theqtcompany { + clear:both; + float:left; + margin:30px 0 8px 3% + } + #footerbar .footer-main .footer-social { + float:left; + padding:50px 0px 0px 3% + } + #footerbar #menu-footer-submenu { + clear:both; + float:none; + display:block; + padding:0px 0px 3.9% 3% + } + ul#menu-footer-submenu { + margin-left: 0 + } +} +.cookies_yum { + background-color:#cecfd5; + display:none; + width:100% +} +.cookies_yum img { + width:25px; + top:6px; + display:inline-block; + position:absolute; + left:13px +} +.cookies_yum div { + margin:0 auto; + max-width:1280px; + min-height:30px; + padding:6px 0px 6px 0px; + position:relative +} +.cookies_yum p { + color:#09102b; + margin:0px; + font-size:0.79em; + display:inline-block; + line-height:1.2; + padding:0 30px 0 50px +} +.cookies_yum p a { + white-space:nowrap +} +.cookies_yum a:hover { + color:#46a2da +} +.cookies_yum .close { + width:15px; + height:15px; + background-image:url("cookiebar-x.png"); + background-size:15px 30px; + background-position:top left; + cursor:pointer; + top:13px; + right:13px; + position:absolute; + transition:none +} +.cookies_yum .close:hover { + background-position:bottom left +} +#sidebar-toggle,#toc-toggle { + width:24px; + height:14px; + background-size:24px 28px; + cursor:pointer; + background-image:url("list_expand.png"); + float:right +} +#sidebar-toggle.collapsed, +#toc-toggle.collapsed { + background-position:bottom left +} +#sidebar-content > h2 { + display:none +} +#footerbar { + background:#222840; + color:#fff; + font-size: 0.9em; +} +#footerbar.fixed { + bottom:0; + left:0; + width:100% +} +#footerbar .footer-nav { + display:inline; + float:left +} +#footerbar .footer-main .footer-nav li { + float:left; + margin-right:1em +} +#footerbar .footer-main .footer-nav li a { + display:block; + padding:30px 0 10px 0; + line-height:20px; + height:20px; + color:#fff; + font-weight: 600; +} +#footerbar .footer-main .footer-nav li a:hover,#footerbar .footer-main .footer-nav li.current-menu-item a { + color:#eee +} +#footerbar .footer-main .footer-nav .sub-menu { + margin-left:0; + margin-bottom:0 +} +#footerbar .footer-main .footer-nav .sub-menu li { + float:none; + width: 100%; +} +#footerbar .footer-main .footer-nav .sub-menu ul { + padding:1px 1em; + font-size:0.786em; + line-height:8px; + float:none; + color:#5d5b59; + margin-bottom:0 +} +#footerbar .footer-main .footer-nav .sub-menu li a { + padding:2px 0; + font-size:1em; + float:none; + color:#cecfd5; + font-weight: 400; +} +#footerbar .footer-main .footer-nav .sub-menu li a:hover,#footerbar .footer-main .footer-nav .sub-menu li.current-menu-item a { + color:#eee +} +#footerbar .theqtcompany { + background:url("theqtcompany.png") no-repeat; + background-size:100%; + width:215px; + height:68px; + display:inline; + float:right; + margin:29px 0 28px 30px +} +#footerbar .footer-social { + display:inline; + float:right; + width:164px +} +#footerbar .footer-main .footer-social>div { + margin-left:0.1em; + margin-bottom:10px +} +#footerbar .disclaimer { + font-size:0.786em; + line-height:2.73; + color:#868584; + padding-top:20px; + padding-bottom:0.5% +} +#footerbar .disclaimer a { + color:#bdbebf +} +#footerbar .disclaimer a:hover { + color:#d6d6d6 +} +#footerbar .disclaimer ul li { + float:left; + vertical-align:middle; + margin-left:1.18em +} +#footerbar .disclaimer ul li:first-child { + margin-left:0 +} +#footerbar .disclaimer ul.lang-selector a { + color:#506a34; + color:rgba(128,195,66,0.3) +} +#footerbar .disclaimer ul.lang-selector a:hover { + color:#80c342; + color:rgba(128,195,66,0.7) +} +#menu-footer-menu, #menu-footer-menu ul { + margin-left:0; + margin-bottom:0 +} +@font-face { + font-family: 'Titillium Web'; + font-style: normal; + font-weight: 400; + src: url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.eot"); + /* IE9 Compat Modes */ + src: local("Titillium Web"), local("TitilliumWeb-Regular"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.eot?#iefix") format("embedded-opentype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.woff2") format("woff2"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.woff") format("woff"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.ttf") format("truetype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-regular.svg#TitilliumWeb") format("svg"); + /* Legacy iOS */ +} +/* titillium-web-italic - latin_latin-ext */ +@font-face { + font-family: 'Titillium Web'; + font-style: italic; + font-weight: 400; + src: url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.eot"); + /* IE9 Compat Modes */ + src: local("Titillium WebItalic"), local("TitilliumWeb-Italic"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.eot?#iefix") format("embedded-opentype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.woff2") format("woff2"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.woff") format("woff"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.ttf") format("truetype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-italic.svg#TitilliumWeb") format("svg"); + /* Legacy iOS */ +} +/* titillium-web-600 - latin_latin-ext */ +@font-face { + font-family: 'Titillium Web'; + font-style: normal; + font-weight: 600; + src: url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.eot"); + /* IE9 Compat Modes */ + src: local("Titillium WebSemiBold"), local("TitilliumWeb-SemiBold"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.eot?#iefix") format("embedded-opentype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.woff2") format("woff2"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.woff") format("woff"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.ttf") format("truetype"), url("//d33sqmjvzgs8hq.cloudfront.net/wp-content/themes/oneqt/assets/fonts/titillium-web-v4-latin_latin-ext-600.svg#TitilliumWeb") format("svg"); + /* Legacy iOS */ +} +@font-face { + font-family:monospace; + font-style:normal; + font-weight:400; + src:local("Droid Sans Mono"),local("DroidSansMono"),url(//fonts.gstatic.com/s/droidsansmono/v7/ns-m2xQYezAtqh7ai59hJUYuTAAIFFn5GTWtryCmBQ4.woff) format("woff") +} +@font-face { + font-family:'Qt Icons'; + src:url("../style/icomoon.eot?-tgjuoj"); + src:url("../style/icomoon.eot?#iefix-tgjuoj") format("embedded-opentype"),url("../style/icomoon.woff?-tgjuoj") format("woff"),url("../style/icomoon.ttf?-tgjuoj") format("truetype"),url("../style/icomoon.svg?-tgjuoj#icomoon") format("svg"); + font-weight:normal; + font-style:normal +} +@font-face { + font-family:'social-icons'; + src:url("../style/social-icons.eot?54625607"); + src:url("../style/social-icons.eot?54625607#iefix") format("embedded-opentype"), + url("../style/social-icons.woff?54625607") format("woff"); + font-weight:normal; + font-style:normal +} +.clearfix:before,.clearfix:after { + content:" "; + display:table +} +.clearfix:after { + clear:both +} +.clearfix { + *zoom:1 +} +.clearfix .right { + float:right +} +html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,img,ins,kbd,q,s,samp,small,strike,strong,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td,article,aside,canvas,details,embed,figure,figcaption,footer,header,hgroup,menu,nav,output,ruby,section,summary,time,mark,audio,video { + margin:0; + padding:0; + border:0; + font-size:100%; + line-height: 1.4; +} +html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,img,ins,kbd,q,s,samp,small,strike,strong,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,caption,article,aside,canvas,details,embed,figure,figcaption,footer,header,hgroup,menu,nav,output,ruby,section,summary,time,mark,audio,video { + vertical-align:baseline +} +h1,h2,h3,h4,h5,h6 { + font-weight:300 +} +.body h2,.body h3,.body h4,.body h5,.body h6 { + margin:1.5em 0 0.75em +} +.body h1 { + margin-bottom:0.75em; + font-size:2.25em; +} +.body h3.fn,.body h3.flags { + color:#26282a; + font-size:1.46em; + padding:15px 0 15px 0; + border-bottom:2px #eee solid; + word-wrap:break-word +} +.body .fngroup { + border-bottom:2px #eee solid; + padding-bottom:15px; + margin-bottom:1.5em +} +.body .fngroup h3.fngroupitem { + margin:0; + padding-bottom:0; + border:none +} +.body h3.fn .name, +.body h3 span.type, +.qmlname span.name { + font-weight: 400 +} +.qmlname { + font-size:1.46em +} +.qmlproto table { + border:none; + border-bottom:2px #eee solid +} +.qmlproto table p { + max-width:100% +} +.qmlproto table tr { + background-color:#fff +} +.qmlname td, .qmlname th { + border:none; + text-align:left; + padding:5px 0 0 0 +} +.qmlreadonly,.qmldefault { + padding:0 5px 0 5px; + font-size:0.75em; + background-color:#eee; + float:right +} +.qmlreadonly { + color:#414141 +} +.qmldefault { + color:#D14141 +} +.rightAlign { + padding:3px 5px 3px 10px; + text-align:right +} +.centerAlign.functionIndex { + text-align:center; + font-size:150%; + margin-bottom: 1em +} +article,aside,details,figcaption,figure,footer,header,hgroup,menu,nav,section { + display:block +} +body { + line-height:1.25em; + font-family: Arial, Helvitica; + font-weight:400; + transition-duration:1s; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + font-size: 16px; + background-color:#f3f3f4; + color:#404244; +} +ol,ul { + list-style-type: square; + #color: #17a81a; +} +.body ol,.body ul { + margin-top:0.75em; + margin-left:20px +} +.bodywrapper ol>li { + list-style-type:decimal; + margin-left:15px +} +.bodywrapper ol.a >li { + list-style-type:lower-alpha; +} +.bodywrapper ol.A >li { + list-style-type:upper-alpha; +} +.bodywrapper ol.i >li { + list-style-type:lower-roman; +} +.bodywrapper ol.I >li { + list-style-type:upper-roman; +} +.body li p { + margin-top:1em +} +blockquote,q { + quotes:none; + border-left:10px solid #ddd; + padding-left:10px +} +blockquote:before,blockquote:after,q:before,q:after { + content:''; + content:none; + width:100% +} +table { + border-collapse:collapse; + border-spacing:0; + margin-bottom:5px; + width:100% +} +a { + color:#17a81a; + text-decoration:none; + transition-duration:0.3s +} +a:hover { + color:#17a81a +} +.main,#footerbar>div { + max-width:1280px; + width:95%; + margin:0 auto +} +.main { + margin-top:80px +} +@media (max-width: 1120px) { + .main,.navbar-header,#footerbar>div { + width: 100%; + margin: 0; + } + .main .main-rounded { + padding: 0 15px; + } +} +.main_index { + background-color:#fff +} +.sectionlist { + margin-bottom:2em +} +[class*="col-"] { + letter-spacing:normal +} +.landing,.main_index .row { + letter-spacing:-0.31em +} +.main_index .row>div { + letter-spacing:normal +} +.col-1,.body { + display:inline-block; + background-color:#fff; + padding: 25px 35px 20px 30px; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box; +} +.col-1 h2 { + font-size:1.8em; + font-weight:300; + line-height:1.1; + margin-bottom:0.83em; + margin-top:1em +} +.icons1of3 img { + display:inline-block; + float:left; + margin-right:0.75em; + margin-top:-5px; + width:2.75em +} +div.multi-column { + position:relative +} +div.multi-column div { + display:-moz-inline-box; + display:inline-block; + vertical-align:top; + margin-top:1em; + margin-right:2em; + width:16em +} +.sidebar { + display:block; + position:relative; + position:sticky; + float:left; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box; + width:20%; + padding-right:20px +} +.sidebar li { + text-overflow:ellipsis; + overflow:hidden +} +.toc,.sectionlist { + padding:25px; + background-color:#fff; + margin-bottom:1.25em +} +.sidebar .sectionlist p { + margin-bottom:0 +} +.sectionlist.promo { + padding:0; + background-color:#f3f3f4 +} +.sidebar-content:empty { + display:none; + visibility:hidden +} +.col-2 h2,.toc h3,.sidebar-content h2, +.sidebar-content h3,.sectionlist h2, +.sphinxsidebar { + position: fixed; + overflow: scroll; + overflow-x: hidden; + overflow-y: hidden; +} +.sphinxsidebar h3 { + font-weight: bold; + margin-bottom:1em; +} +.toc h3 a { + color:#404244 +} +.title { + font-size:2.25em; + font-weight:300; + letter-spacing:-1px; + line-height:1.15em; + margin-bottom:0.5em; + word-wrap:break-word +} +.navigationbar,col-1 h2 { + font-size:0.85em +} +.navigationbar h1 { + font-size:2.5em; + margin-bottom:0.85em; + margin-top:0.85em +} +.navigationbar li { + display:inline-block; + margin-right:5px; + position:relative; + padding-right:10px; + color:#585a5c +} +.navigationbar ul:last-of-type li a { + color:#404244 +} +.sectionlist li, .sphinxsidebar li { + padding-bottom: 10px; + line-height: 1.75em; +} +.col-1 ul { + margin-bottom:1.56em +} +.bodywrapper li { + margin-top:0.5em; + line-height:1.25em +} +.bodywrapper li.level2 { + margin-left:10px; + margin-top:0.4em; + font-size:0.9375em; +} +.bodywrapper p, +.bodywrapper dd { + line-height:1.25em; + margin:1em 0 1em; + color:#404244 +} +.bodywrapper b { + font-weight:600 +} +.body ul,.body ol { + /* margin-bottom:1.5em */ +} +.bodywrapper ul ul { + margin-top:0.5em +} +.bodywrapper .naviNextPrevious { + margin-top:25px; + max-width:100% +} +.naviNextPrevious.headerNavi, +p.naviNextPrevious + p { + display:none +} +.nextPage { + float:right +} +.prevPage:before { + content:"< " +} +.nextPage:after { + content:" >" +} +.navigationbar li a { + color:#404244 +} +.navigationbar li:after { + color:#404244; + content:"›"; + display:inline-block; + font-size:1.5em; + line-height:1; + position:absolute; + right:-2px; + top:-4px +} +.sub-navigation { + margin-top:10px +} +.navigationbar li:last-child:after,.sub-navigation li:after { + content:none +} +.navigationbar { + margin-bottom:10px; + line-height:1em +} +#buildversion { + margin-bottom:10px; + font-style:italic; + font-size:small; + float:right +} +.copy-notice { + width:75%; + font-size:0.75em; + margin:20px 35px 0 10px; + line-height:1.75em; + float:right; + color:#585a5c +} +.copy-notice.index { + margin-top:10px; + float:none +} +li a.active { + color:#585a5c +} +.flowList { + padding:25px +} +.flowListDiv dl { + -webkit-column-count:1; + -moz-column-count:1; + column-count:1 +} +.flowList dd { + display:inline-block; + margin-left:10px; + width:90%; + line-height:1.15em; + overflow-x:hidden; + text-overflow:ellipsis +} +.alphaChar { + font-size:2em; + position:absolute +} +.flowList.odd { + background-color:#f9f9f9 +} +.body ul>li,.doc-column ul>li { + list-style-image:url("list_arrow.png"); + margin-left:15px; + color:#404244; + margin-top:0.65em; + line-height:1em +} +.bodywrapper table p { + margin:0px; + padding:0px +} +.bodywrapper table p { + margin:0px; + padding:0px; + min-height:1.25em +} +.bodywrapper .qmldoc { + margin-top:0.75em +} +.body h2 { + margin-top: 1.5em; + font-size:1.75em +} +.body h3 { + font-size:1.35em +} +.body h4 { + font-size:1.15em +} +.body p img { + margin-top:0.75em; + max-width:100% +} +.body .border img { + box-shadow:3px 3px 8px 3px rgba(200,200,200,0.5) +} +.body .border .player { + box-shadow:3px 3px 8px 3px rgba(200,200,200,0.5) +} +.body p.figCaption { + transform:translateY(-30px); + color:#606366; + font-size:95%; + margin-left:3px; + font-style:italic +} +.body table { + width:initial; + vertical-align:initial +} +table .odd { + background-color:#f9f9f9 +} +table thead { + text-align:left; + padding-left:20px +} +table,table td,table th { + border:1px solid #eee +} +table td,table th { + padding:5px 20px; + line-height:1.3 +} +.body .fixed table td { + min-width:50%; + width:50% +} +table.alignedsummary,table.propsummary { + width:initial +} +table.valuelist td.tblval { + font-size:0.75em +} +div.main_index .row { + border-bottom:10px solid #f3f3f4 +} +div.main_index .row { + position:relative +} +div.main_index .row>div { + display:inline-block; + width:50%; + vertical-align:top; + padding:2em 3em; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box +} +div.main_index h2 { + font-size:2.1875em; + margin-bottom:1em +} +#search_bar { + width:40%; + float:right +} +div.main_index .row:after { + content:""; + position:absolute; + top:0; + right:50%; + height:100%; + width:10px; + background-color:#f3f3f4 +} +div.table { + overflow-x:auto +} +.body tr > td > pre { + font-size:0.75em +} +p.qt_commercial { + border:3px solid #5caa15; + margin:0 auto; + padding:15px; + width:28%; + text-align:center; + clear:both +} +h1.qt_commercial { + padding:20px; + background-color:#5caa15; + display:inline; + float:right; + font-size:1.25em; + line-height:1.25em; + height:1.25em; + color:#fff +} +div.qt_commercial { + border-top:5px solid #5caa15; + margin-bottom:50px +} +div.pre { + position:relative; + height:auto +} +pre, .LegaleseLeft { + background-color:#222840; + color:#fff; + display:block; + font-family:monospace; + line-height:1.5; + overflow-x:auto; + margin-bottom:25px; + padding:25px; + margin-top:0.75em; + font-size: .8em; +} +.bodywrapper .LegaleseLeft p { + color:#fff; + white-space: pre-wrap +} +pre .str,code .str { + color:#aaaaaa +} +pre .kwd,code .kwd { + color:#ffff55 +} +pre .com,code .com { + color:#55ffff +} +pre .typ,code .typ { + color:#4f9d08 +} +pre a .typ,code a .typ { + color:#21be2b +} +pre .lit,code .lit { + color:#ff55ff +} +pre .pun,code .pun { + color:#fff +} +pre .pln,code .pln { + color:#fff +} +@media print { + pre { + background-color:#eee !important + } + pre .str,code .str { + color:#060 + } + pre .kwd,code .kwd{ + color:#006; + font-weight:bold + } + pre .com,code .com { + color:#600 + } + pre .typ,code .typ { + color:#404; + font-weight:bold + } + pre .lit,code .lit { + color:#044 + } + pre .pun,code .pun { + color:#440 + } + pre .pln,code .pln { + color:#000 + } +} +pre.wrap { + white-space:pre-wrap +} +pre span.wrap { + display:none; + background:url("wrap.png") no-repeat; + right:0; + top:2px; + position:absolute; + width:20px; + height:14px; + margin:4px; + opacity:0.65 +} + +span.pre { + color: #09102d; +} + +span.wrap:hover { + opacity:1 +} +span.wrap:active { + opacity:0.75 +} +.copy_text { + background-color:#46a2da; + color:#fff; + border:2px solid #46a2da; + padding:10px 16px; + margin-left:-10px; + margin-top:-50px; + position:absolute; + opacity:0; + cursor:pointer; + float:right +} +.copy_text:hover { + background-color:#fff; + color:#46a2da +} +code,.codelike { + font-family:monospace; +} +#detailed-description .function dt > code, +#detailed-description .function dt > em { + font-weight:bold +} +h3.fn code { + font-size:0.75em; + float:right; + background-color:#eee; + padding:3px; + margin: 3px 0 0 20px +} +pre:hover>.copy_text { + display:inline-block; + opacity:1; + transition:0.5s ease +} +#main_title_bar { + background:url("pyside-logo.png") no-repeat; + background-size:100%; + width:366px; + height:86px; + margin:15px 0 15px 0 +} +#main_title_bar h1 { + visibility:hidden +} +#main_title_bar .search_bar { + letter-spacing:normal; + width:50%; + display:inline-block; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box; + vertical-align:middle +} +#main_title_bar h1 { + letter-spacing:normal; + display:inline-block; + -webkit-box-sizing:border-box; + -moz-box-sizing:border-box; + -ms-box-sizing:border-box; + box-sizing:border-box; + vertical-align:middle +} +#main_title_bar .search_bar * { + letter-spacing:normal; + padding:0; + margin:0; + border:none +} +#sidebar-toggle,#toc-toggle { + display:none +} +@media (max-width: 980px) { + body { + font-size:calc-em(14px) + } + #main_title_bar>h1,#main_title_bar .search_bar { + width:100% + } + #main_title_bar .search_bar { + margin-bottom:15px + } + .main { + margin-top:0px + } + .main_index .row { + border:none !important + } + .title { + font-size:1.5em; + font-weight:400; + word-wrap:break-word + } + .col-1,.body,.naviNextPrevious,.sidebar { + padding:10px + } + .sidebar { + position:relative; + padding-top:0 + } + .search .sidebar { + display:none; + visibility:hidden + } + .col-2 h2,.toc h3,.sidebar-content h2,.sidebar-content h3,.sectionlist h2 { + text-align:center; + margin-bottom:5px + } + div.main_index .row:after { + content:none + } + div.main_index .row>div { + display:block !important; + width:100%; + padding:15px; + margin:0 + } + .body,.sidebar,.col-1 { + width:100% + } + .sidebar-content,.col-2,.toc { + background-color:#fff; + margin-bottom:1em; + padding:20px + } + #sidebar-toggle,#toc-toggle { + display:block + } + #sidebar-toggle.collapsed + h2 { + display:block + } + .bodywrapper p { + margin-bottom:1em; + max-width:100% + } + table td,table th { + padding:5px 5px + } + .sectionlist { + padding:0 + } + .sidebar > .sectionlist { + padding:20px + } + .sectionlist.promo { + max-width:46%; + margin:0 auto 1em auto; + float:left; + padding:0 2% + } + .sidebar .sidebar-content { + clear:both + } + .copy-notice { + float:none; + width:initial + } +} +[id]:target > *:first-child, +dt[id]:target { + -webkit-animation:highlighter 3s; + animation:highlighter 3s +} +@-webkit-keyframes highlighter { + 25% { + background-color:#d1e8f6; + color:#444 + } + 75% { + background-color:#d1e8f6; + color:#444 + } +} +@keyframes highlighter { + 25% { + background-color:#d1e8f6; + color:#444 + } + 75% { + background-color:#d1e8f6; + color:#444 + } +} +@-webkit-keyframes copypaste { + 25% { + opacity:1 + } + 100% { + border-radius:10px; + margin-top:-50px; + opacity:1 + } +} +@keyframes copypaste { + 25% { + opacity:1 + } + 100% { + border-radius:10px; + margin-top:-50px; + opacity:1 + } +} +#footer { + clear:both +} +.footer-social i { + font-family: "social-icons"; + font-style: normal; + font-size:150%; + margin: .55em; + color: #cecfd5 +} +.footer-social i:hover { + color: #eee +} +.footer-social .icon-twitter:before { + content: '\f099' +} +.footer-social .icon-facebook:before { + content: '\f09a' +} +.footer-social .icon-youtube:before { + content: '\f16a' +} +.menuextraslanguages { + display:none; + visibility:hidden +} + +input:focus { + border-color: #46a2da; + box-shadow: 0 0 5px #46a2da; + color: #000; +} + +.animation { + width: 100%; + border-style: none; + border-width: 0 +} + +.player { + width: auto; + position: relative; + display: table; + margin-bottom:1.5em; +} + +.playcontrol { + display: none; + background: url("play_icon.svg") no-repeat center, + linear-gradient( + rgba(0,0,0,0.15), rgba(0,0,0,0.15) + ); + background-size: 25%; + width: 100%; + height: 100%; + position: absolute; + left: 0%; + right: 0%; + top: 0%; + bottom: 0%; + margin: auto +} + +/* expand/collapse code sections */ +pre input { + display:none; + visibility:hidden +} +pre label { + display:block; + margin:-3px 3px 0 -16px; + text-align:center; + color:#21be2b; + float:left; +} +pre label:hover { + color:#fff +} +pre label::before { + font-weight:600; + font-size:16px; + content:"+"; + display:inline-block; + width:16px; + height:16px +} +#ec_expand { + height:16px; + overflow:hidden; + transition:height 0.35s; +} +#ec_expand::before { + content:"...*/"; + color:#aaa; + background-color:#3a4055; + z-index:99 !important; + right:25px; + position:absolute +} +#ec_toggle:checked ~ #ec_expand { + height:initial +} +#ec_toggle:checked ~ #ec_expand::before { + content:"" +} +#ec_toggle:checked ~ label::before { + content:"-" +} + +/* permalinks */ +h1:hover > .headerlink, +h2:hover > .plink, +h2:hover > .headerlink, +h3:hover > .plink, +h3:hover > .headerlink, +h4:hover > .plink, +h4:hover > .headerlink, +h5:hover > .plink, +h5:hover > .headerlink { + opacity:1 +} +a.plink, a.headerlink { + opacity: 0; + padding-left: 8px; + font-size: 0.8em; + font-weight: 600; + transition: opacity 180ms ease-in-out +} +a.plink::before { + content:'\00B6' +} + +table.special { + border: 3px; + padding: 0px; + border-collapse: separate; + border-spacing: 20px; + line-height: 1.5em; +} + +.special p { + text-align: center; + color: #3a4055; +} + +.special a { + display: block; + border-bottom: 0; + text-decoration: none; +} + +.special a:hover { + border-bottom: 0; + text-decoration: none; +} + +.special strong { + color: #17a81a; + font-size: 110%; + font-weight: normal; +} + +table.special th, +table.special td { + border: 1px solid #888; + padding-top: 14px; + padding-bottom: 14px; + padding-left: 6px; + padding-right: 5px; + border-radius: 5px; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; +} + +.special td:hover { + padding-top: 2px; + padding-bottom: 2px; + border-bottom: 4px solid #41cd52; +} diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/pysidelogo.png b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/pysidelogo.png Binary files differnew file mode 100644 index 000000000..3a2f2bd17 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/pysidelogo.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/relbar_bg.png b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/relbar_bg.png Binary files differnew file mode 100644 index 000000000..4036733a7 --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/static/relbar_bg.png diff --git a/sources/shiboken6/doc/_themes/pysidedocs_qthelp/theme.conf b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/theme.conf new file mode 100644 index 000000000..4384b459c --- /dev/null +++ b/sources/shiboken6/doc/_themes/pysidedocs_qthelp/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = default +stylesheet = pyside.css +pygments_style = none + +[options] +nosidebar = true diff --git a/sources/shiboken6/doc/conf.py.in b/sources/shiboken6/doc/conf.py.in new file mode 100644 index 000000000..f99af0fff --- /dev/null +++ b/sources/shiboken6/doc/conf.py.in @@ -0,0 +1,168 @@ +# -*- coding: utf-8 -*- +# +# PyQtB documentation build configuration file, created by +# sphinx-quickstart on Wed Apr 22 15:04:20 2009. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.append(os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig', +'sphinx.ext.coverage'] + +output_format='@DOC_OUTPUT_FORMAT@' + +def setup(app): + app.add_config_value('output_format','qthelp','env') +rst_epilog = """ + +.. |project| replace:: Shiboken +""" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Shiboken' +copyright = u'© 2018 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/license/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '@shiboken_VERSION@' +# The full version, including alpha/beta/rc tags. +release = '@shiboken_VERSION@' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'pysidedocs' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = { +#} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_themes'] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = { '' : ''} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = { 'index' : 'index.html'} + +# If false, no module index is generated. +html_use_modindex = False + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# -- Options for qthelp output -------------------------------------------------- +qthelp_theme = 'pysidedocs_qthelp' diff --git a/sources/shiboken6/doc/considerations.rst b/sources/shiboken6/doc/considerations.rst new file mode 100644 index 000000000..3488c3407 --- /dev/null +++ b/sources/shiboken6/doc/considerations.rst @@ -0,0 +1,183 @@ +.. _words-of-advice: + +*************** +Words of Advice +*************** + +When writing or using Python bindings there is some things you must keep in mind. + + +.. _duck-punching-and-virtual-methods: + +Duck punching and virtual methods +================================= + +The combination of duck punching, the practice of altering class characteristics +of already instantiated objects, and virtual methods of wrapped C++ classes, can +be tricky. That was an optimistic statement. + +Let's see duck punching in action for educational purposes. + + .. code-block:: python + + import types + import Binding + + obj = Binding.CppClass() + + # CppClass has a virtual method called 'virtualMethod', + # but we don't like it anymore. + def myVirtualMethod(self_obj, arg): + pass + + obj.virtualMethod = types.MethodType(myVirtualMethod, obj, Binding.CppClass) + + +If some C++ code happens to call `CppClass::virtualMethod(...)` on the C++ object +held by "obj" Python object, the new duck punched "virtualMethod" method will be +properly called. That happens because the underlying C++ object is in fact an instance +of a generated C++ class that inherits from `CppClass`, let's call it `CppClassWrapper`, +responsible for receiving the C++ virtual method calls and finding out the proper Python +override to which handle such a call. + +Now that you know this, consider the case when C++ has a factory method that gives you +new C++ objects originated somewhere in C++-land, in opposition to the ones generated in +Python-land by the usage of class constructors, like in the example above. + +Brief interruption to show what I was saying: + + .. code-block:: python + + import types + import Binding + + obj = Binding.createCppClass() + def myVirtualMethod(self_obj, arg): + pass + + # Punching a dead duck... + obj.virtualMethod = types.MethodType(myVirtualMethod, obj, Binding.CppClass) + + +The `Binding.createCppClass()` factory method is just an example, C++ created objects +can pop out for a number of other reasons. Objects created this way have a Python wrapper +holding them as usual, but the object held is not a `CppClassWrapper`, but a regular +`CppClass`. All virtual method calls originated in C++ will stay in C++ and never reach +a Python virtual method overridden via duck punching. + +Although duck punching is an interesting Python feature, it don't mix well with wrapped +C++ virtual methods, specially when you can't tell the origin of every single wrapped +C++ object. In summary: don't do it! + + +.. _pyside-old-style-class: + +Python old style classes and PySide +=================================== + +Because of some architectural decisions and deprecated Python types. +Since PySide 1.1 old style classes are not supported with multiple inheritance. + +Below you can check the examples: + +Example with old style class: + + .. code-block:: python + + from PySide2 import QtCore + + class MyOldStyleObject: + pass + + class MyObject(QtCore, MyOldStyleObject): + pass + + +this example will raise a 'TypeError' due to the limitation on PySide, to fix +this you will need use the new style class: + + + .. code-block:: python + + from PySide2 import QtCore + + class MyOldStyleObject(object): + pass + + class MyObject(QtCore, MyOldStyleObject): + pass + + +All classes used for multiple inheritance with other PySide types need to have +'object' as base class. +************************** +Frequently Asked Questions +************************** + +This is a list of Frequently Asked Questions about |project|. +Feel free to suggest new entries using our `Mailing list`_ or our IRC channel! + +General +======= + +What is Shiboken? +----------------- + +Shiboken is a Generator Runner plugin that outputs C++ code for CPython +extensions. +The first version of PySide had source code based on Boost templates. +It was easier to produce code but a paradigm change was needed, as the next +question explains. + + +Why did you switch from Boost.Python to Shiboken? +------------------------------------------------- + +The main reason was the size reduction. Boost.Python makes excessive use of +templates resulting in a significant increase of the binaries size. +On the other hand, as Shiboken generates CPython code, the resulting binaries +are smaller. + +Creating bindings +================= + +Can I wrap non-Qt libraries? +---------------------------- + +Yes. Check Shiboken source code for an example (libsample). + + +Is there any runtime dependency on the generated binding? +--------------------------------------------------------- + +Yes. Only libshiboken, and the obvious Python interpreter +and the C++ library that is being wrapped. + +What do I have to do to create my bindings? +------------------------------------------- + +Most of the work is already done by the API Extractor. +The developer creates a :std:doc:`typesystem <typesystem>` +file with any customization wanted in +the generated code, like removing classes or changing method signatures. +The generator will output the *.h* and *.cpp* files with the CPython code that +will wrap the target library for python. + + +Is there any recommended build system? +-------------------------------------- + +Both API Extractor and generator uses and recommends the CMake build system. + +Can I write closed-source bindings with the generator? +------------------------------------------------------ + +Yes, as long as you use a LGPL version of Qt, due to runtime requirements. + +What is 'inject code'? +---------------------- + +That's how we call customized code that will be *injected* into the +generated at specific locations. They are specified inside the typesystem. + +.. _`Mailing list`: http://lists.qt-project.org/mailman/listinfo/pyside diff --git a/sources/shiboken6/doc/dependency-pyside.svg b/sources/shiboken6/doc/dependency-pyside.svg new file mode 100644 index 000000000..786bdb8a6 --- /dev/null +++ b/sources/shiboken6/doc/dependency-pyside.svg @@ -0,0 +1,527 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="900" + height="560" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.46" + version="1.0" + sodipodi:docname="dependency-pyside.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="/tmp/dependency-pyside.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path3270" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(0.8,0,0,0.8,10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible"> + <path + id="path3679" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.79440331" + inkscape:cx="-36.66006" + inkscape:cy="372.04724" + inkscape:document-units="px" + inkscape:current-layer="svg2" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="1278" + inkscape:window-height="949" + inkscape:window-x="0" + inkscape:window-y="0"> + <sodipodi:guide + orientation="1,0" + position="384.28571,590" + id="guide2601" /> + <sodipodi:guide + orientation="1,0" + position="678.57143,491.42857" + id="guide2603" /> + <sodipodi:guide + orientation="1,0" + position="78.571429,257.14286" + id="guide2605" /> + <sodipodi:guide + orientation="1,0" + position="93.571429,280.71429" + id="guide7565" /> + <sodipodi:guide + orientation="1,0" + position="148.57143,216.42857" + id="guide7567" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-78.088635,-190.95252)" /> + <g + id="g5394" + transform="translate(6.1314759,14.304617)"> + <g + transform="translate(-65.84289,-190.95252)" + id="g5205"> + <g + id="g5171"> + <rect + rx="9.3643799" + y="338.7739" + x="678.57141" + height="73.281754" + width="274.54263" + id="rect2393" + style="fill:#aaeeff;fill-rule:evenodd;stroke:#006078;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="13.104657" /> + <text + id="text2395" + y="355.93701" + x="683.46539" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="355.93701" + x="683.46539" + id="tspan2397" + sodipodi:role="line">boost::python</tspan></text> + <text + id="text2399" + y="371.60172" + x="683.46539" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="371.60172" + x="683.46539" + id="tspan2401" + sodipodi:role="line">1.38.0</tspan></text> + <text + id="text2403" + y="387.14166" + x="683.46539" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2435" + y="387.14166" + x="683.46539" + sodipodi:role="line">headers and libraries - compile-time and run-time</tspan></text> + <text + id="text2413" + y="402.4646" + x="683.46539" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="402.4646" + x="683.46539" + id="tspan2415" + sodipodi:role="line">Boost Software License 1.0</tspan></text> + </g> + <g + id="g5193"> + <rect + rx="8.3239012" + y="342.86383" + x="78.571426" + height="73.282379" + width="274.18781" + id="rect2417" + style="fill:#b3ff80;fill-rule:evenodd;stroke:#2a7800;stroke-width:0.96558368px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="9.2689295" /> + <text + id="text2419" + y="359.67014" + x="88.822823" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="359.67014" + x="88.822823" + id="tspan2421" + sodipodi:role="line">Qt 4.5</tspan></text> + <text + id="text2423" + y="375.33484" + x="88.822823" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="375.33484" + x="88.822823" + id="tspan2425" + sodipodi:role="line">4.5</tspan></text> + <text + id="text2427" + y="390.87479" + x="88.822823" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="390.87479" + x="88.822823" + id="tspan2429" + sodipodi:role="line">headers and libraries - compile-time and run-time</tspan></text> + <text + id="text2431" + y="400.84058" + x="88.822823" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="400.84058" + x="88.822823" + id="tspan2433" + sodipodi:role="line">GNU General Public License v3 /</tspan><tspan + y="411.1687" + x="88.822823" + sodipodi:role="line" + id="tspan2472">GNU Lesser General Public Licence v2.1</tspan></text> + </g> + <g + id="g5120"> + <rect + y="496.43558" + x="384.28571" + height="73.281754" + width="274.54263" + id="rect2441" + style="fill:#e9ddaf;fill-rule:evenodd;stroke:#5f5019;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="13.104635" + rx="10.404889" /> + <text + id="text2443" + y="513.59869" + x="389.17969" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="513.59869" + x="389.17969" + id="tspan2445" + sodipodi:role="line">libapiextractor</tspan></text> + <text + id="text2447" + y="529.26337" + x="389.17969" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="529.26337" + x="389.17969" + id="tspan2449" + sodipodi:role="line">0.1</tspan></text> + <text + id="text2451" + y="544.80334" + x="389.17969" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2453" + y="544.80334" + x="389.17969" + sodipodi:role="line">headers and libraries - compile-time and run-time</tspan></text> + <text + id="text2455" + y="560.12628" + x="389.17969" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="560.12628" + x="389.17969" + id="tspan2457" + sodipodi:role="line">LGPL version 2.1</tspan></text> + </g> + <g + id="g5131"> + <rect + y="340.72134" + x="384.28571" + height="73.281754" + width="274.54263" + id="rect2459" + style="fill:#e9ddaf;fill-rule:evenodd;stroke:#5f5019;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="10.309408" + rx="9.3644047" /> + <text + id="text2461" + y="357.88449" + x="389.17969" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="357.88449" + x="389.17969" + id="tspan2463" + sodipodi:role="line">BoostPythonGenerator</tspan></text> + <text + id="text2465" + y="373.54916" + x="389.17969" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="373.54916" + x="389.17969" + id="tspan2467" + sodipodi:role="line">0.1</tspan></text> + <text + id="text2469" + y="389.08914" + x="389.17969" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2471" + y="389.08914" + x="389.17969" + sodipodi:role="line">Binary executable - compile-time</tspan></text> + <text + id="text2473" + y="404.41208" + x="389.17969" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="404.41208" + x="389.17969" + id="tspan2475" + sodipodi:role="line">LGPL version 2.1</tspan></text> + </g> + <g + id="g5142"> + <rect + y="191.43562" + x="384.28571" + height="73.281754" + width="274.54263" + id="rect2523" + style="fill:#e9ddaf;fill-opacity:1;fill-rule:evenodd;stroke:#5f5019;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="14.285714" /> + <text + id="text2525" + y="208.59874" + x="389.17966" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="208.59874" + x="389.17966" + id="tspan2527" + sodipodi:role="line">Qt Python bindings</tspan></text> + <text + id="text2529" + y="224.26344" + x="389.17966" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="224.26344" + x="389.17966" + id="tspan2531" + sodipodi:role="line">0.1</tspan></text> + <text + id="text2533" + y="239.80339" + x="389.17966" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2535" + y="239.80339" + x="389.17966" + sodipodi:role="line">Target</tspan></text> + <text + id="text2537" + y="255.12633" + x="389.17966" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="255.12633" + x="389.17966" + id="tspan2539" + sodipodi:role="line">LGPL version 2.1</tspan></text> + </g> + <g + id="g5182"> + <rect + rx="10.404877" + y="648.57843" + x="384.28571" + height="73.281754" + width="274.54263" + id="rect2563" + style="fill:#aaeeff;fill-rule:evenodd;stroke:#006078;stroke-width:0.96620417px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + ry="11.287985" /> + <text + id="text2565" + y="665.74158" + x="389.17969" + style="font-size:16.27989578px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="665.74158" + x="389.17969" + id="tspan2567" + sodipodi:role="line">boost::graph</tspan></text> + <text + id="text2569" + y="681.40625" + x="389.17969" + style="font-size:8.40044498px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="681.40625" + x="389.17969" + id="tspan2571" + sodipodi:role="line">1.38.0</tspan></text> + <text + id="text2573" + y="696.94623" + x="389.17969" + style="font-size:9.33067703px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan2575" + y="696.94623" + x="389.17969" + sodipodi:role="line">headers and libraries - compile-time and run-time</tspan></text> + <text + id="text2577" + y="712.26917" + x="389.17969" + style="font-size:8.26250458px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="712.26917" + x="389.17969" + id="tspan2579" + sodipodi:role="line">Boost Software License 1.0</tspan></text> + </g> + </g> + <path + inkscape:connector-type="polyline" + id="path2869" + d="M 212.85114,151.42852 L 368.56822,74.247959" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <path + inkscape:connector-type="polyline" + id="path2871" + d="M 663.60462,147.33826 L 517.61788,74.247959" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <path + inkscape:connector-type="polyline" + id="path2877" + d="M 443.4684,149.28571 L 443.46839,74.247959" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <path + inkscape:connector-type="polyline" + id="path2879" + d="M 443.4684,304.99994 L 443.4684,223.53367" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-end:none;stroke-opacity:1" /> + <path + inkscape:connector-type="polyline" + id="path2881" + d="M 443.4684,457.14279 L 443.4684,379.2479" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;marker-start:url(#Arrow1Lstart);marker-mid:none;marker-end:none;stroke-opacity:1" /> + <rect + ry="17.142857" + y="293.85626" + x="0.48279184" + height="124.28571" + width="211.42857" + id="rect7541" + style="fill:#e3e2db;stroke:#000000;stroke-opacity:1" /> + <text + id="text7543" + y="325.44049" + x="70.482788" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="325.44049" + x="70.482788" + id="tspan7545" + sodipodi:role="line">Boost</tspan></text> + <text + id="text7547" + y="358.37042" + x="70.482788" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="358.37042" + x="70.482788" + id="tspan7549" + sodipodi:role="line">Qt Software</tspan></text> + <text + id="text7551" + y="394.07593" + x="70.482788" + style="font-size:20.61732101px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + y="394.07593" + x="70.482788" + id="tspan7553" + sodipodi:role="line">INdT/Nokia</tspan></text> + <rect + ry="6.4285707" + y="307.24911" + x="15.482792" + height="22.5" + width="43.163269" + id="rect7555" + style="fill:#aaeeff;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" /> + <rect + ry="6.4285707" + y="341.17767" + x="15.482792" + height="22.5" + width="43.163269" + id="rect7561" + style="fill:#b3ff80;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" /> + <rect + ry="6.4285707" + y="376.17767" + x="15.482792" + height="22.5" + width="43.163269" + id="rect7563" + style="fill:#e9ddaf;fill-opacity:1;stroke:#000000;stroke-width:0.64285713;stroke-opacity:1" /> + </g> +</svg> diff --git a/sources/shiboken6/doc/examples/index.rst b/sources/shiboken6/doc/examples/index.rst new file mode 100644 index 000000000..92a64195e --- /dev/null +++ b/sources/shiboken6/doc/examples/index.rst @@ -0,0 +1,9 @@ +Examples +======== + +C++ examples +------------ + +.. toctree:: + + samplebinding.rst diff --git a/sources/shiboken6/doc/examples/samplebinding.rst b/sources/shiboken6/doc/examples/samplebinding.rst new file mode 100644 index 000000000..a53b32bac --- /dev/null +++ b/sources/shiboken6/doc/examples/samplebinding.rst @@ -0,0 +1,246 @@ +SampleBinding Example +*********************** + +This example showcases how you can use Shiboken to generate CPython-based +binding code for a C++ library. The C++ library is called :code:`Universe`, +with two classes: :code:`Icecream` and :code:`Truck`. Ice-creams are +characterized by their flavor, and :code:`Truck` serves as a vehicle of +:code:`Icecream` distribution for kids in a neighborhood. + +First, let's look at the definition of the two classes: + +.. code-block:: cpp + :caption: icecream.h + + class Icecream + { + public: + Icecream(const std::string &flavor); + virtual Icecream *clone(); + virtual ~Icecream(); + virtual const std::string getFlavor(); + + private: + std::string m_flavor; + }; + +.. code-block:: cpp + :caption: truck.h + + class Truck { + public: + Truck(bool leaveOnDestruction = false); + Truck(const Truck &other); + Truck& operator=(const Truck &other); + ~Truck(); + + void addIcecreamFlavor(Icecream *icecream); + void printAvailableFlavors() const; + + bool deliver() const; + void arrive() const; + void leave() const; + + void setLeaveOnDestruction(bool value); + void setArrivalMessage(const std::string &message); + + private: + void clearFlavors(); + + bool m_leaveOnDestruction = false; + std::string m_arrivalMessage = "A new icecream truck has arrived!\n"; + std::vector m_flavors; + }; + +Here's a summary of what's included in the :code:`Universe` library: + +* The :code:`Icecream` polymorphic type, which is intended to be overridden. +* The :code:`Icecream::getFlavor()` method returns the flavor depending on the + actual derived type. +* The :code:`Truck` value type that contains pointers, hence the copy + constructor. +* :code:`Truck` stores the :code:`Icecream` objects in a vector, which can be + modified via :code:`Truck::addIcecreamFlavor()`. +* The :code:`Truck’s` arrival message can be customized using its + :code:`setArrivalMessage()` method. +* The :code:`Truck::deliver()` method tells us if the ice-cream delivery was + successful. + +Shiboken typesystem +==================== + +Now that the library definitions are in place, the Shiboken generator needs a +header file that includes the types we are interested in: + +.. code-block:: cpp + :caption: bindings.h + + #ifndef BINDINGS_H + #define BINDINGS_H + #include "icecream.h" + #include "truck.h" + #endif // BINDINGS_H + +In addition, Shiboken also requires an XML-based typesystem file that defines the +relationship between C++ and Python types: + +.. code-block:: xml + :caption: bindings.xml + + <?xml version="1.0"?> + <typesystem package="Universe"> + <primitive-type name="bool"/> + <primitive-type name="std::string"/> + <object-type name="Icecream"> + <modify-function signature="clone()"> + <modify-argument index="0"> + <define-ownership owner="c++"/> + </modify-argument> + </modify-function> + </object-type> + <value-type name="Truck"> + <modify-function signature="addIcecreamFlavor(Icecream*)"> + <modify-argument index="1"> + <define-ownership owner="c++"/> + </modify-argument> + </modify-function> + </value-type> + </typesystem> + +One important thing to notice here is that we declare :code:`"bool"` and +:code:`"std::string"` as primitive types. These types are used by some of the +C++ methods as parameters or return types, so Shiboken must know about them. +Then, Shiboken can generate relevant conversion code between C++ and Python, although +most C++ primitive types are handled by Shiboken without additional code. + +Next, we declare the two aforementioned classes. One of them as an +“object-type” and the other as a “value-type”. The main difference is that +object-types are passed around in generated code as pointers, whereas +value-types are copied (value semantics). + +By specifying the names of these classes in the typesystem file, Shiboken +automatically tries to generate bindings for all methods of those +classes. You need not mention all the methods manually in the XML file, unless +you want to modify them. + +Object ownership rules +======================= + +Shiboken doesn't know if Python or C++ are responsible for freeing the C++ objects that were +allocated in the Python code, and assuming this might lead to errors. +There can be cases where Python should release the C++ memory when the reference count of the +Python object becomes zero, but it should never delete the underlying C++ object just from +assuming that it will not be deleted by underlying C++ library, or if it's maybe parented to +another object (like QWidgets). + +In our case, the :code:`clone()` method is only called inside the C++ library, +and we assume that the C++ code takes care of releasing the cloned object. + +As for :code:`addIcecreamFlavor()`, we know that a :code:`Truck` owns the +:code:`Icecream` object, and will remove it once the :code:`Truck` is +destroyed. That's why the ownership is set to “c++” in the typesystem file, +so that the C++ objects are not deleted when the corresponding Python names +go out of scope. + +Build +===== + +To build the :code:`Universe` custom library and then generate bindings for it, +use the :file:`CMakeLists.txt` file provided with the example. Later, you can reuse +the file for your own libraries with minor changes. + +Now, run the :command:`"cmake ."` command from the prompt to configure the +project and build with the toolchain of your choice; we recommend the +‘(N)Makefiles’ generator. + +As a result, you end up with two shared libraries: +:file:`libuniverse.(so/dylib/dll)` and :file:`Universe.(so/pyd)`. The former is +the custom C++ library, and the latter is the Python module to import in your +Python script. + +For more details about these platforms, see the :file:`README.md` file. + +Use the Python module +===================== + +The following script uses the :code:`Universe` module, derives a few types from +:code:`Icecream`, implements virtual methods, instantiates objects, and much more: + +.. code-block:: python + :caption: main.py + + from Universe import Icecream, Truck + + class VanillaChocolateIcecream(Icecream): + def __init__(self, flavor=""): + super(VanillaChocolateIcecream, self).__init__(flavor) + + def clone(self): + return VanillaChocolateIcecream(self.getFlavor()) + + def getFlavor(self): + return "vanilla sprinked with chocolate" + + class VanillaChocolateCherryIcecream(VanillaChocolateIcecream): + def __init__(self, flavor=""): + super(VanillaChocolateIcecream, self).__init__(flavor) + + def clone(self): + return VanillaChocolateCherryIcecream(self.getFlavor()) + + def getFlavor(self): + base_flavor = super(VanillaChocolateCherryIcecream, self).getFlavor() + return base_flavor + " and a cherry" + + if __name__ == '__main__': + leave_on_destruction = True + truck = Truck(leave_on_destruction) + + flavors = ["vanilla", "chocolate", "strawberry"] + for f in flavors: + icecream = Icecream(f) + truck.addIcecreamFlavor(icecream) + + truck.addIcecreamFlavor(VanillaChocolateIcecream()) + truck.addIcecreamFlavor(VanillaChocolateCherryIcecream()) + + truck.arrive() + truck.printAvailableFlavors() + result = truck.deliver() + + if result: + print("All the kids got some icecream!") + else: + print("Aww, someone didn't get the flavor they wanted...") + + if not result: + special_truck = Truck(truck) + del truck + + print("") + special_truck.setArrivalMessage("A new SPECIAL icecream truck has arrived!\n") + special_truck.arrive() + special_truck.addIcecreamFlavor(Icecream("SPECIAL *magical* icecream")) + special_truck.printAvailableFlavors() + special_truck.deliver() + print("Now everyone got the flavor they wanted!") + special_truck.leave() + +After importing the classes from the :code:`Universe` module, it derives two +types from :code:`Icecream` for different “flavors”. It then creates a +:code:`truck` to deliver some regular flavored Icecreams and two special ones. + +If the delivery fails, a new :code:`truck` is created with the old flavors +copied over, and a new *magical* flavor that will surely satisfy all customers. + +Try running it to see if the ice creams are delivered. + +.. note:: + You can find the sources for this example under + :file:`<PYTHON_ENV_ROOT>/site-packages/lib/PySide2/examples/samplebinding`. + +Refer to the following topics for detailed information about using Shiboken: + * :doc:`Type System Variables <../typesystem_variables>` + * :doc:`User Defined Type Conversion <../typesystem_converters>` + * :doc:`Object ownership <../typesystem_ownership>` + * :doc:`Considerations and Frequently Asked Questions <../considerations>` diff --git a/sources/shiboken6/doc/gettingstarted.rst b/sources/shiboken6/doc/gettingstarted.rst new file mode 100644 index 000000000..758bc9763 --- /dev/null +++ b/sources/shiboken6/doc/gettingstarted.rst @@ -0,0 +1,72 @@ +Getting started +=============== + +Building from source +-------------------- + +This step is focused on building Shiboken from source, both the Generator and Python module. +Please notice that these are built when you are building PySide from source too, so there is no +need to continue if you already have a built PySide. + +General Requirements +^^^^^^^^^^^^^^^^^^^^ + + * **Python**: 3.5+ and 2.7 + * **Qt:** 5.12+ (5.15 is recommended) + * **libclang:** The libclang library, recommended: version 10 for Shiboken6 5.15. + Prebuilt versions of it can be `downloaded here`_. + * **CMake:** 3.1+ is needed. + +.. _downloaded here: http://download.qt.io/development_releases/prebuilt/libclang/ + +Simple build +^^^^^^^^^^^^ + +If you need only Shiboken Generator, a simple build run would look like this:: + + # For the required libraries (this will also build the shiboken6 python module) + python setup.py install --qmake=/path/to/qmake \ + --build-tests \ + --verbose-build \ + --internal-build-type=shiboken6 + + # For the executable + python setup.py install --qmake=/path/to/qmake \ + --build-tests \ + --verbose-build \ + --internal-build-type=shiboken6-generator + +The same can be used for the module, changing the value of ``internal-build-type`` to +``shiboken6-module``. + +.. warning:: If you are planning to use PySide too, for examples like + 'scriptableapplication' you need to have build it as well. The main issue is + that your PySide and Shiboken needs to be build using the same dependencies + from Qt and libclang. + +Using the wheels +---------------- + +Installing ``pyside2`` or ``shiboken6`` from pip **does not** install ``shiboken6_generator``, +because the wheels are not on PyPi. + +You can get the ``shiboken6_generator`` wheels from Qt servers, and you can still install it +via ``pip``:: + + pip install \ + --index-url=http://download.qt.io/official_releases/QtForPython/ \ + --trusted-host download.qt.io \ + shiboken6 pyside2 shiboken6_generator + + +The ``whl`` package cannot automatically discover in your system the location for: + +* Clang installation, +* ``qmake`` location with the same version as the one described in the wheel, +* Qt libraries with the same package version. + +So using this process requires you to manually modify the variables: + +* ``CLANG_INSTALL_DIR`` must be set to where the libraries are, +* ``PATH`` must include the location for a ``qmake`` with the same Qt version as the package, +* ``LD_LIBRARY_PATH`` including the Qt libraries and Clang libraries paths. diff --git a/sources/shiboken6/doc/images/.directory b/sources/shiboken6/doc/images/.directory new file mode 100644 index 000000000..e65475f65 --- /dev/null +++ b/sources/shiboken6/doc/images/.directory @@ -0,0 +1,3 @@ +[Dolphin] +ShowPreview=true +Timestamp=2009,5,5,17,43,26 diff --git a/sources/shiboken6/doc/images/bindinggen-development.png b/sources/shiboken6/doc/images/bindinggen-development.png Binary files differnew file mode 100644 index 000000000..5931b126a --- /dev/null +++ b/sources/shiboken6/doc/images/bindinggen-development.png diff --git a/sources/shiboken6/doc/images/bindinggen-development.svg b/sources/shiboken6/doc/images/bindinggen-development.svg new file mode 100644 index 000000000..591e1f2d1 --- /dev/null +++ b/sources/shiboken6/doc/images/bindinggen-development.svg @@ -0,0 +1,542 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="640" + height="200" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.92.2 2405546, 2018-03-11" + version="1.0" + sodipodi:docname="bindinggen-development.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="bindinggen-development.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <marker + inkscape:stockid="EmptyDiamondL" + orient="auto" + refY="0" + refX="0" + id="EmptyDiamondL" + style="overflow:visible"> + <path + id="path3930" + d="M 0,-7.0710768 L -7.0710894,0 L 0,7.0710589 L 7.0710462,0 L 0,-7.0710768 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="scale(0.8,0.8)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleInL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleInL" + style="overflow:visible"> + <path + id="path3975" + d="M 5.77,0 L -2.88,5 L -2.88,-5 L 5.77,0 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,4.8,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Sstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Sstart" + style="overflow:visible"> + <path + id="path3835" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(0.2,0,0,0.2,1.2,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend" + style="overflow:visible"> + <path + id="path3832" + d="M 0,0 L 5,-5 L -12.5,0 L 5,5 L 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + </marker> + <marker + inkscape:stockid="Tail" + orient="auto" + refY="0" + refX="0" + id="Tail" + style="overflow:visible"> + <g + id="g3859" + transform="scale(-1.2,-1.2)"> + <path + id="path3861" + d="M -3.8048674,-3.9585227 L 0.54352094,0" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3863" + d="M -1.2866832,-3.9585227 L 3.0617053,0" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3865" + d="M 1.3053582,-3.9585227 L 5.6537466,0" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3867" + d="M -3.8048674,4.1775838 L 0.54352094,0.21974226" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3869" + d="M -1.2866832,4.1775838 L 3.0617053,0.21974226" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3871" + d="M 1.3053582,4.1775838 L 5.6537466,0.21974226" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + </g> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3636" + style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.97309,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.76787377" + inkscape:cx="286.61779" + inkscape:cy="101.18182" + inkscape:document-units="px" + inkscape:current-layer="g5440" + showgrid="false" + inkscape:window-width="1116" + inkscape:window-height="1042" + inkscape:window-x="10" + inkscape:window-y="28" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-maximized="0"> + <sodipodi:guide + orientation="1,0" + position="-557.55608,678.10875" + id="guide7299" + inkscape:locked="false" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-1758.7331,-2056.8567)"> + <flowRoot + xml:space="preserve" + id="flowRoot3229" + style="font-style:normal;font-weight:normal;line-height:0.01%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + transform="translate(4.1137413,-2.3429609)"><flowRegion + id="flowRegion3231"><rect + id="rect3233" + width="125.74072" + height="40.5849" + x="388.45547" + y="279.5423" /></flowRegion><flowPara + id="flowPara3235" + style="font-size:40px;line-height:1.25"> </flowPara></flowRoot> <g + id="g5658" + transform="translate(6.5767925,7.0112479)"> + <g + transform="matrix(0,-1,1,0,697.50638,3244.256)" + id="g5624" + style=""> + <g + id="g5626" + transform="matrix(0,-1,1,0,-294.81158,2953.0504)" + style=""> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path5628" + d="m 1586.5317,1348.2858 0.091,41.5266" + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + inkscape:connector-curvature="0" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + d="m 1586.7489,1389.4756 7.9979,-9.1068" + id="path5630" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + d="m 1586.6031,1389.5063 -7.9979,-9.1069" + id="path5632" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + transform="matrix(0,-1,1,0,908.50929,3242.9612)" + id="g5648" + style=""> + <g + id="g5650" + transform="matrix(0,-1,1,0,-294.81158,2953.0504)" + style=""> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path5652" + d="m 1586.5317,1348.2858 0.091,41.5266" + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + inkscape:connector-curvature="0" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + d="m 1586.7489,1389.4756 7.9979,-9.1068" + id="path5654" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + d="m 1586.6031,1389.5063 -7.9979,-9.1069" + id="path5656" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + </g> + </g> + <g + id="g5634" + style=""> + <g + id="g6271" + transform="translate(1086.3689,746.93837)" + style=""> + <g + transform="matrix(0,-1,1,0,-294.81158,2953.0504)" + id="g6252" + style=""> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + d="m 1586.5317,1300.2858 0.091,89.5266" + id="path11089" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path2758" + d="m 1586.7489,1389.4756 7.9979,-9.1068" + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path2760" + d="m 1586.6031,1389.5063 -7.9979,-9.1069" + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + inkscape:connector-curvature="0" /> + </g> + </g> + </g> + <g + id="g5641" + style=""> + <g + id="g5465" + transform="translate(874.42628,746.93837)" + style=""> + <g + transform="matrix(0,-1,1,0,-294.81158,2953.0504)" + id="g5467" + style=""> + <path + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + d="m 1586.5317,1300.2858 0.091,89.5266" + id="path5469" + inkscape:connector-type="polyline" + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path5471" + d="m 1586.7489,1389.4756 7.9979,-9.1068" + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-type="polyline" + id="path5473" + d="m 1586.6031,1389.5063 -7.9979,-9.1069" + style="display:inline;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-start:none" + inkscape:connector-curvature="0" /> + </g> + </g> + </g> + <g + transform="translate(-194.79968,-212.08495)" + id="g5440"> + <path + style="fill:#41cd52;fill-opacity:1;stroke:none;stroke-width:2.18747473;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 2378.6251,2292.247 v 66.9548 h 171.1068 l 14.8788,-14.8788 v -66.9549 h -171.1068 z" + id="path3715-5-6-7-9-8-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:0%;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.29069424px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;" + x="2471.614" + y="2309.093" + id="text5174"><tspan + sodipodi:role="line" + x="2471.614" + y="2309.093" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.29069424px;" + id="tspan953">Qt for Python</tspan><tspan + id="tspan6109" + sodipodi:role="line" + x="2471.614" + y="2339.093" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.29069424px;">(generated code)</tspan></text> + <path + style="fill:#6b7080;fill-opacity:1;stroke:none;stroke-width:2.18747473;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 2166.5963,2292.247 v 66.9548 h 171.1068 l 14.8788,-14.8788 v -66.9549 h -171.1068 z" + id="path3715-5-6-7-9-8-7-9-94" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:0%;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.50930572px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;" + x="2259.1294" + y="2311.0505" + id="text3627" + transform="scale(1.0000266,0.9999734)"><tspan + id="tspan3697" + sodipodi:role="line" + x="2259.1294" + y="2311.0505" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.50930572px;">generator</tspan><tspan + sodipodi:role="line" + x="2259.1294" + y="2341.0505" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.50930572px;" + id="tspan2464">front-end</tspan></text> + <path + style="fill:#6b7080;fill-opacity:1;stroke:none;stroke-width:2.18747473;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 1959.8625,2292.2469 v 66.9548 h 171.1068 l 14.8788,-14.8788 v -66.9549 h -171.1068 z" + id="path3715-5-6-7-9-8-7-9-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + id="text3168" + y="2326.4568" + x="2052.7678" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:0%;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.65129721px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;" + xml:space="preserve"><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.65129721px;" + y="2326.4568" + x="2052.7678" + sodipodi:role="line" + id="tspan5424">API Extractor</tspan></text> + <path + style="fill:#9d9faa;fill-opacity:1;stroke:none;stroke-width:2.18747473;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 2378.6251,2393.0867 v 66.9548 h 171.1068 l 14.8788,-14.8788 v -66.9549 h -171.1068 z" + id="path3715-5-6-7-9-8-7-9-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + id="text3487" + y="2410.3647" + x="2471.614" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:0%;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.44197154px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;" + xml:space="preserve"><tspan + id="tspan2509" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.44197154px;" + y="2410.3647" + x="2471.614" + sodipodi:role="line">typesystem</tspan><tspan + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.44197154px;" + y="2440.3647" + x="2471.614" + sodipodi:role="line" + id="tspan5432">(handwritten)</tspan></text> + <path + style="fill:#9d9faa;fill-opacity:1;stroke:none;stroke-width:2.18747473;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 2166.5963,2394.0075 v 66.9548 h 171.1068 l 14.8788,-14.8788 v -66.9549 h -171.1068 z" + id="path3715-5-6-7-9-8-7-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:0%;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.58586931px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;" + x="2259.5852" + y="2412.0415" + id="text2735"><tspan + sodipodi:role="line" + x="2259.5852" + y="2412.0415" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.58586931px;" + id="tspan2737">injected code</tspan><tspan + id="tspan2743" + sodipodi:role="line" + x="2259.5852" + y="2442.0415" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:24px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:1.58586931px;">(handwritten)</tspan></text> + </g> + <g + transform="translate(-102.30216,-279.71223)" + id="g5541" + style="stroke:none"> + <path + sodipodi:type="arc" + style="fill:#f28888;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:3, 3;stroke-dashoffset:0;stroke-opacity:1" + id="path5535" + sodipodi:cx="255.10791" + sodipodi:cy="326.69064" + sodipodi:rx="38.848923" + sodipodi:ry="38.848923" + d="m 293.95683,326.69064 a 38.848923,38.848923 0 0 1 -38.84892,38.84893 38.848923,38.848923 0 0 1 -38.84892,-38.84893 38.848923,38.848923 0 0 1 38.84892,-38.84892 38.848923,38.848923 0 0 1 38.84892,38.84892 z" + transform="matrix(0.4405339,0,0,0.4405339,1842.2283,2282.9708)" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:Titillium;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;-inkscape-font-specification:'Titillium, Normal';font-stretch:normal;font-variant:normal;font-size:26.66666667px;text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal" + x="1946.3259" + y="2435.7" + id="text5537"><tspan + sodipodi:role="line" + id="tspan5539" + x="1946.3259" + y="2435.7" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:26.66666667px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;stroke:none">1</tspan></text> + </g> + <g + transform="translate(52.589867,-352.69787)" + id="g5546" + style="stroke:none"> + <path + sodipodi:type="arc" + style="fill:#f28888;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:3, 3;stroke-dashoffset:0;stroke-opacity:1" + id="path5548" + sodipodi:cx="255.10791" + sodipodi:cy="326.69064" + sodipodi:rx="38.848923" + sodipodi:ry="38.848923" + d="m 293.95683,326.69064 a 38.848923,38.848923 0 0 1 -38.84892,38.84893 38.848923,38.848923 0 0 1 -38.84892,-38.84893 38.848923,38.848923 0 0 1 38.84892,-38.84892 38.848923,38.848923 0 0 1 38.84892,38.84892 z" + transform="matrix(0.4405339,0,0,0.4405339,1842.2283,2282.9708)" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:Titillium;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;-inkscape-font-specification:'Titillium, Normal';font-stretch:normal;font-variant:normal;font-size:26.66666667px;text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal" + x="1946.3259" + y="2435.7" + id="text5550"><tspan + sodipodi:role="line" + id="tspan5552" + x="1946.3259" + y="2435.7" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:26.66666667px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;stroke:none">2</tspan></text> + </g> + <g + transform="translate(200.4676,-222.96766)" + id="g5554" + style="stroke:none"> + <path + sodipodi:type="arc" + style="fill:#f28888;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:3, 3;stroke-dashoffset:0;stroke-opacity:1" + id="path5556" + sodipodi:cx="255.10791" + sodipodi:cy="326.69064" + sodipodi:rx="38.848923" + sodipodi:ry="38.848923" + d="m 293.95683,326.69064 a 38.848923,38.848923 0 0 1 -38.84892,38.84893 38.848923,38.848923 0 0 1 -38.84892,-38.84893 38.848923,38.848923 0 0 1 38.84892,-38.84892 38.848923,38.848923 0 0 1 38.84892,38.84892 z" + transform="matrix(0.4405339,0,0,0.4405339,1842.2283,2282.9708)" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:Titillium;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;-inkscape-font-specification:'Titillium, Normal';font-stretch:normal;font-variant:normal;font-size:26.66666667px;text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal" + x="1946.3259" + y="2435.7" + id="text5558"><tspan + sodipodi:role="line" + id="tspan5560" + x="1946.3259" + y="2435.7" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:26.66666667px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;stroke:none">3</tspan></text> + </g> + <g + transform="translate(413.633,-206.84535)" + id="g5562" + style="stroke:none"> + <path + sodipodi:type="arc" + style="fill:#f28888;fill-opacity:1;stroke:none;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:3, 3;stroke-dashoffset:0;stroke-opacity:1" + id="path5564" + sodipodi:cx="255.10791" + sodipodi:cy="326.69064" + sodipodi:rx="38.848923" + sodipodi:ry="38.848923" + d="m 293.95683,326.69064 a 38.848923,38.848923 0 0 1 -38.84892,38.84893 38.848923,38.848923 0 0 1 -38.84892,-38.84893 38.848923,38.848923 0 0 1 38.84892,-38.84892 38.848923,38.848923 0 0 1 38.84892,38.84892 z" + transform="matrix(0.4405339,0,0,0.4405339,1842.2283,2282.9708)" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:Titillium;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;-inkscape-font-specification:'Titillium, Normal';font-stretch:normal;font-variant:normal;font-size:26.66666667px;text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal" + x="1946.3259" + y="2435.7" + id="text5566"><tspan + sodipodi:role="line" + id="tspan5568" + x="1946.3259" + y="2435.7" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:26.66666667px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;stroke:none">4</tspan></text> + </g> + </g> + </g> +</svg> diff --git a/sources/shiboken6/doc/images/boostgen.png b/sources/shiboken6/doc/images/boostgen.png Binary files differnew file mode 100644 index 000000000..ae9d9fc3d --- /dev/null +++ b/sources/shiboken6/doc/images/boostgen.png diff --git a/sources/shiboken6/doc/images/converter.png b/sources/shiboken6/doc/images/converter.png Binary files differnew file mode 100644 index 000000000..cd52e2769 --- /dev/null +++ b/sources/shiboken6/doc/images/converter.png diff --git a/sources/shiboken6/doc/images/converter.svg b/sources/shiboken6/doc/images/converter.svg new file mode 100644 index 000000000..4305eb720 --- /dev/null +++ b/sources/shiboken6/doc/images/converter.svg @@ -0,0 +1,349 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="206.375mm" + height="100.54167mm" + viewBox="0 0 206.375 100.54167" + version="1.1" + id="svg8" + inkscape:version="0.92.2 2405546, 2018-03-11" + sodipodi:docname="converter.svg"> + <defs + id="defs2"> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker1623" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path1621" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker1569" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path1567" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker1521" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend" + inkscape:collect="always"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path1519" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker1479" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path1477" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker1443" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend" + inkscape:collect="always"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path1441" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path1154" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.35" + inkscape:cx="382.16184" + inkscape:cy="-28.417621" + inkscape:document-units="mm" + inkscape:current-layer="layer1" + showgrid="true" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + inkscape:window-width="1002" + inkscape:window-height="1042" + inkscape:window-x="10" + inkscape:window-y="28" + inkscape:window-maximized="0"> + <inkscape:grid + type="xygrid" + id="grid971" + originx="-58.208333" + originy="-68.791657" /> + </sodipodi:namedview> + <metadata + id="metadata5"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-58.208333,-127.66667)"> + <path + style="fill:#17a81a;fill-opacity:1;stroke:none;stroke-width:0.82824755;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 127,132.95834 0.0687,26.45833 h 63.43127 l 5.29167,-5.29167 v -26.45833 h -63.5 z" + id="path3715-5-6-7-9-8-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <path + style="fill:#3a4055;fill-opacity:1;stroke:none;stroke-width:0.67261654;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 68.791667,132.95834 v 26.45833 H 105.83333 L 111.125,154.125 V 127.66667 H 74.083333 Z" + id="path3715-5-6-7-9-8-7-6-3" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <path + style="fill:#848895;fill-opacity:1;stroke:none;stroke-width:0.52087492;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M 58.208333,173.96875 V 185.875 h 48.947917 l 3.96875,-3.96875 V 170 H 62.177083 Z" + id="path3715-5-6-7-9-8-7-6-56" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <path + style="fill:#17a81a;fill-opacity:1;stroke:none;stroke-width:0.82824755;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 127.00003,175.29167 0.0687,26.45833 H 190.5 l 5.29167,-5.29167 V 170 h -63.5 z" + id="path3715-5-6-7-9-8-7-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <path + style="fill:#848895;fill-opacity:1;stroke:none;stroke-width:0.52087492;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 58.208333,195.13542 v 11.90625 h 48.947917 l 3.96875,-3.96875 V 191.16667 H 62.177083 Z" + id="path3715-5-6-7-9-8-7-6-56-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <path + style="fill:#848895;fill-opacity:1;stroke:none;stroke-width:0.52087492;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 58.208343,216.30209 v 11.90625 h 48.947907 l 3.96875,-3.96875 V 212.33334 H 62.177093 Z" + id="path3715-5-6-7-9-8-7-6-56-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.05555534px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="65.68634" + y="179.68727" + id="text1032"><tspan + sodipodi:role="line" + id="tspan1030" + x="65.68634" + y="179.68727" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.05555534px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332">PythonType1</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.05555534px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="65.326508" + y="200.85394" + id="text1032-1"><tspan + sodipodi:role="line" + id="tspan1030-1" + x="65.326508" + y="200.85394" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.05555534px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332">PythonType2</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.05555534px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="65.319458" + y="222.02061" + id="text1032-4"><tspan + sodipodi:role="line" + id="tspan1030-6" + x="65.319458" + y="222.02061" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.05555534px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332">PythonType3</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:10.58333302px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:Titillium;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="90.120621" + y="139.29776" + id="text1062"><tspan + sodipodi:role="line" + id="tspan1060" + x="90.120621" + y="139.29776" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:9.87777805px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332">C++</tspan><tspan + sodipodi:role="line" + x="90.120621" + y="152.52693" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:9.87777805px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332" + id="tspan1064">Type</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:10.58333302px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:Titillium;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="135.41069" + y="138.95909" + id="text1068"><tspan + sodipodi:role="line" + id="tspan1066" + x="135.41069" + y="138.95909" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46666622px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332">Converter</tspan><tspan + sodipodi:role="line" + x="135.41069" + y="152.18826" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46666622px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332" + id="tspan1070">C++ -> Python</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:10.58333302px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:Titillium;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="135.41072" + y="181.29242" + id="text1068-9"><tspan + sodipodi:role="line" + id="tspan1066-7" + x="135.41072" + y="181.29242" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46666622px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332">Converter</tspan><tspan + sodipodi:role="line" + x="135.41072" + y="194.52159" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:8.46666622px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332" + id="tspan1070-5">Python -> C++</tspan></text> + <path + style="fill:#3a4055;fill-opacity:1;stroke:none;stroke-width:0.67261654;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M 211.66667,175.29167 V 201.75 h 37.04166 L 254,196.45833 V 170 h -37.04167 z" + id="path3715-5-6-7-9-8-7-6-3-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:10.58333302px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:Titillium;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="232.99562" + y="181.63109" + id="text1062-7"><tspan + sodipodi:role="line" + id="tspan1060-4" + x="232.99562" + y="181.63109" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:9.87777805px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332">C++</tspan><tspan + sodipodi:role="line" + x="232.99562" + y="194.86026" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:9.87777805px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:center;writing-mode:lr-tb;text-anchor:middle;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332" + id="tspan1064-9">Type</tspan></text> + <path + style="fill:#848895;fill-opacity:1;stroke:none;stroke-width:0.52087492;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 211.66667,131.63542 v 11.90625 h 48.94791 l 3.96875,-3.96875 v -11.90625 h -48.94791 z" + id="path3715-5-6-7-9-8-7-6-56-0-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.05555534px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.26458332" + x="220.67876" + y="137.35394" + id="text1032-4-7"><tspan + sodipodi:role="line" + id="tspan1030-6-0" + x="220.67876" + y="137.35394" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:7.05555534px;font-family:Titillium;-inkscape-font-specification:'Titillium, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.26458332">PythonType</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:0.26499999;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Lend)" + d="M 111.125,143.54167 H 127" + id="path1149" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker1443)" + d="M 111.125,175.29167 H 127" + id="path1433" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker1479)" + d="M 111.125,196.45834 127,185.875" + id="path1469" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker1521)" + d="M 111.125,217.625 127,201.75" + id="path1511" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker1569)" + d="m 195.79166,185.875 h 15.875" + id="path1559" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:0.26458332px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker1623)" + d="m 195.79166,138.25001 h 15.875" + id="path1613" + inkscape:connector-curvature="0" /> + </g> +</svg> diff --git a/sources/shiboken6/doc/images/genrunnerarch.png b/sources/shiboken6/doc/images/genrunnerarch.png Binary files differnew file mode 100644 index 000000000..db1077cd0 --- /dev/null +++ b/sources/shiboken6/doc/images/genrunnerarch.png diff --git a/sources/shiboken6/doc/images/genrunnerarch.svg b/sources/shiboken6/doc/images/genrunnerarch.svg new file mode 100644 index 000000000..ea7eb73e7 --- /dev/null +++ b/sources/shiboken6/doc/images/genrunnerarch.svg @@ -0,0 +1,654 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="980" + height="380" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.47pre4 r22446" + version="1.0" + sodipodi:docname="genrunnerarch.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="genrunnerarch.png" + inkscape:export-xdpi="56.549999" + inkscape:export-ydpi="56.549999"> + <defs + id="defs4"> + <marker + inkscape:stockid="EmptyDiamondL" + orient="auto" + refY="0" + refX="0" + id="EmptyDiamondL" + style="overflow:visible"> + <path + id="path3930" + d="M 0,-7.0710768 -7.0710894,0 0,7.0710589 7.0710462,0 0,-7.0710768 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="scale(0.8,0.8)" /> + </marker> + <marker + inkscape:stockid="EmptyTriangleInL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleInL" + style="overflow:visible"> + <path + id="path3975" + d="m 5.77,0 -8.65,5 0,-10 8.65,5 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,4.8,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Sstart" + orient="auto" + refY="0" + refX="0" + id="Arrow1Sstart" + style="overflow:visible"> + <path + id="path3835" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(0.2,0,0,0.2,1.2,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend" + style="overflow:visible"> + <path + id="path3832" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.4,0,0,-0.4,-4,0)" /> + </marker> + <marker + inkscape:stockid="Tail" + orient="auto" + refY="0" + refX="0" + id="Tail" + style="overflow:visible"> + <g + id="g3859" + transform="scale(-1.2,-1.2)"> + <path + id="path3861" + d="M -3.8048674,-3.9585227 0.54352094,0" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3863" + d="M -1.2866832,-3.9585227 3.0617053,0" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3865" + d="M 1.3053582,-3.9585227 5.6537466,0" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3867" + d="M -3.8048674,4.1775838 0.54352094,0.21974226" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3869" + d="M -1.2866832,4.1775838 3.0617053,0.21974226" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + <path + id="path3871" + d="M 1.3053582,4.1775838 5.6537466,0.21974226" + style="fill:none;stroke:#000000;stroke-width:0.80000001;stroke-linecap:round;marker-start:none;marker-end:none" /> + </g> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3636" + style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective3033" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective3881" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective3915" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective3956" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5100" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5322" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5365" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5391" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <marker + inkscape:stockid="EmptyTriangleInL" + orient="auto" + refY="0" + refX="0" + id="EmptyTriangleInL-4" + style="overflow:visible"> + <path + id="path3975-9" + d="m 5.77,0 -8.65,5 0,-10 8.65,5 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="matrix(-0.8,0,0,-0.8,4.8,0)" /> + </marker> + <inkscape:perspective + id="perspective5621" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <inkscape:perspective + id="perspective5643" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <marker + inkscape:stockid="EmptyDiamondL" + orient="auto" + refY="0" + refX="0" + id="EmptyDiamondL-7" + style="overflow:visible"> + <path + id="path3930-7" + d="M 0,-7.0710768 -7.0710894,0 0,7.0710589 7.0710462,0 0,-7.0710768 z" + style="fill:#ffffff;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" + transform="scale(0.8,0.8)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.0716799" + inkscape:cx="460.27913" + inkscape:cy="148.01364" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="1862" + inkscape:window-height="1019" + inkscape:window-x="20" + inkscape:window-y="89" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-maximized="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(472.44407,-697.53823)"> + <flowRoot + xml:space="preserve" + id="flowRoot3229" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + transform="translate(2.0918751e-6,-6.0000008)"><flowRegion + id="flowRegion3231"><rect + id="rect3233" + width="125.74072" + height="40.5849" + x="388.45547" + y="279.5423" /></flowRegion><flowPara + id="flowPara3235" /></flowRoot> <g + id="g5867" + transform="translate(6.7062969,-7.6922472)"> + <rect + rx="3.4968286" + ry="5.2462597" + y="713.31403" + x="-472.05276" + height="363.61459" + width="393.78473" + id="rect3609" + style="fill:#e4fae3;fill-opacity:0.65882353;stroke:#8eff89;stroke-width:0.78260708;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + transform="scale(1.0000266,0.9999734)" + id="text3601" + y="742.43872" + x="-275.16165" + style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan3605" + style="font-size:27.09890556px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="742.43872" + x="-275.16165" + sodipodi:role="line"><tspan + id="tspan2508" + style="font-weight:bold">API Extractor</tspan></tspan></text> + <g + transform="matrix(0.9678438,0,0,0.9677923,-587.62742,-106.48682)" + id="g3763"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.79775763;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3737" + width="244.82956" + height="101.59812" + x="267.06232" + y="905.13727" + ry="3.1522403" + rx="2.4096873" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="389.39117" + y="931.86993" + id="text3739"><tspan + sodipodi:role="line" + x="389.39117" + y="931.86993" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan3741">ApiExtractor</tspan><tspan + id="tspan2523" + sodipodi:role="line" + x="389.39117" + y="953.38947" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">commands the parsing and</tspan><tspan + id="tspan2517" + sodipodi:role="line" + x="389.39117" + y="973.38947" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">building of the data model</tspan><tspan + id="tspan2519" + sodipodi:role="line" + x="389.39117" + y="993.38947" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">and calls the user generators</tspan></text> + </g> + <rect + rx="2.1814992" + ry="5.2485871" + y="713.45312" + x="219.72128" + height="363.77597" + width="274.11292" + id="rect9190" + style="fill:#b8d1f1;fill-opacity:0.51184836;stroke:#0045a4;stroke-width:0.6182732;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + transform="scale(1.0000266,0.9999734)" + id="text9192" + y="742.66901" + x="357.65579" + style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#002e7a;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan9194" + style="font-size:27.09890556px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002e7a;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="742.66901" + x="357.65579" + sodipodi:role="line"><tspan + id="tspan2512" + style="font-weight:bold;fill:#002e7a;fill-opacity:1">front-end</tspan><tspan + id="tspan2514" + style="font-size:22px;fill:#002e7a;fill-opacity:1" /></tspan></text> + <rect + rx="2.2192271" + ry="5.2485123" + y="713.23639" + x="-68.659073" + height="363.77075" + width="278.85358" + id="rect9190-9" + style="fill:#cbe990;fill-opacity:0.51184836;stroke:#6ca400;stroke-width:0.62359226;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + transform="scale(1.0000266,0.9999734)" + id="text9192-3" + y="741.71094" + x="70.291061" + style="font-size:38.71272278px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + id="tspan9194-7" + style="font-size:26px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + y="741.71094" + x="70.291061" + sodipodi:role="line">Generator Runner</tspan></text> + <g + transform="matrix(0.9678438,0,0,0.9677923,-687.04869,-241.74888)" + id="g9234-4"> + <rect + style="fill:#addc52;fill-opacity:1;stroke:#6ca400;stroke-width:0.73640609;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect9206-4" + width="218.17299" + height="83.517967" + x="694.6994" + y="1044.8701" + ry="2.5912752" + rx="2.4978092" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="803.78589" + y="1072.3693" + id="text9208-3"><tspan + sodipodi:role="line" + x="803.78589" + y="1072.3693" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan9210-0">Generator</tspan><tspan + id="tspan9222-8" + sodipodi:role="line" + x="803.78589" + y="1093.8888" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">base class for front-end</tspan><tspan + id="tspan3946" + sodipodi:role="line" + x="803.78589" + y="1113.8888" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">output classes</tspan></text> + </g> + <g + transform="matrix(0.9678438,0,0,0.9677923,-726.09128,-46.791689)" + id="g10497-6"> + <rect + style="fill:#89b3e7;fill-opacity:1;stroke:#0049a4;stroke-width:1.04736876;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect10444-8" + width="256.05252" + height="143.95157" + x="990.81482" + y="843.58032" + ry="4.4663219" + rx="2.9314826" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="1118.0945" + y="873.04047" + id="text10446-8"><tspan + sodipodi:role="line" + x="1118.0945" + y="873.04047" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan10448-4">SpecificGenerator</tspan><tspan + id="tspan4063" + sodipodi:role="line" + x="1118.0945" + y="894.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">generators written for any</tspan><tspan + id="tspan5381" + sodipodi:role="line" + x="1118.0945" + y="914.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">desired output,</tspan><tspan + id="tspan4065" + sodipodi:role="line" + x="1118.0945" + y="934.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans"> e.g.: HppGenerator,</tspan><tspan + id="tspan4071" + sodipodi:role="line" + x="1118.0945" + y="954.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">CppGenerator,</tspan><tspan + id="tspan4073" + sodipodi:role="line" + x="1118.0945" + y="974.56" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#002758;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">ConverterGenerator</tspan></text> + </g> + <path + sodipodi:nodetypes="cc" + transform="translate(109.91989,748.26874)" + id="path4056" + d="m -201.98482,41.728896 76.97065,5e-6" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:6, 1;stroke-dashoffset:0" /> + <path + sodipodi:nodetypes="cc" + id="path4056-2" + d="m 197.04022,787.89746 35.38656,0" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-start:url(#EmptyTriangleInL)" /> + <g + transform="matrix(0.9678438,0,0,0.9677923,-1010.4541,91.401187)" + id="g10497"> + <rect + style="fill:#addc52;fill-opacity:1;stroke:#6ca400;stroke-width:0.88060772;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect10444" + width="256.21927" + height="101.69494" + x="990.73145" + y="843.49695" + ry="3.1552441" + rx="2.9333918" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:start;text-anchor:start;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="1012.22" + y="870.08466" + id="text10446"><tspan + sodipodi:role="line" + x="1012.22" + y="870.08466" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:start;text-anchor:start;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan10448">Generator App</tspan><tspan + id="tspan10456" + sodipodi:role="line" + x="1012.22" + y="891.60419" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;text-anchor:start;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">* loads generators</tspan><tspan + id="tspan5353" + sodipodi:role="line" + x="1012.22" + y="911.60419" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;text-anchor:start;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">* setup API Extractor</tspan><tspan + id="tspan5355" + sodipodi:role="line" + x="1012.22" + y="931.60419" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;text-anchor:start;fill:#050800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">* executes each generator</tspan></text> + </g> + <path + sodipodi:nodetypes="cc" + id="path4056-9" + d="m 72.409302,850.57374 0,56.99122" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:6, 1;stroke-dashoffset:0" /> + <path + sodipodi:nodetypes="ccc" + id="path4056-2-0" + d="m -86.437722,825.54499 52.188784,0 0.06367,81.67009" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0;marker-start:url(#EmptyDiamondL)" /> + <path + sodipodi:nodetypes="cc" + id="path4056-91" + d="m -394.83596,853.70064 0,121.42437" + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:6, 1;stroke-dashoffset:0" /> + <g + transform="matrix(0.9678438,0,0,0.9677923,-707.18032,-153.53291)" + id="g3809"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:1.00168562;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3785" + width="332.48172" + height="82.830231" + x="302.83319" + y="1068.9153" + ry="3.1461167" + rx="3.8065021" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="469.03497" + y="1095.5493" + id="text3787"><tspan + id="tspan3791" + sodipodi:role="line" + x="469.03497" + y="1095.5493" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold">AbstractMetaBuilder</tspan><tspan + sodipodi:role="line" + x="469.03497" + y="1117.0688" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" + id="tspan3807">builds the data model with information</tspan><tspan + id="tspan2545" + sodipodi:role="line" + x="469.03497" + y="1137.0688" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">from headers and binding directives</tspan><tspan + id="tspan3795" + sodipodi:role="line" + x="469.03497" + y="1157.0688" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans" /></text> + </g> + <g + transform="matrix(0.9678438,0,0,0.9677923,-755.89347,194.37862)" + id="g3709"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.69825613;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect2821" + width="198.90968" + height="93.892342" + x="305.2475" + y="807.38849" + ry="2.6812849" + rx="2.1703238" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="405.17499" + y="831.81903" + id="text3611"><tspan + id="tspan3687" + sodipodi:role="line" + x="405.17499" + y="831.81903" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold">TypeDatabase</tspan><tspan + id="tspan5641" + sodipodi:role="line" + x="405.17499" + y="853.33856" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">parses typesystem</tspan><tspan + id="tspan3689" + sodipodi:role="line" + x="405.17499" + y="873.33856" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">and stores information</tspan></text> + </g> + <g + transform="matrix(0.9678438,0,0,0.9677923,-589.50555,-13.923919)" + id="g3728"> + <rect + style="fill:#bff3bc;fill-opacity:1;stroke:#0af400;stroke-width:0.54871088;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect3625" + width="117.15066" + height="86.355225" + x="133.25664" + y="809.36938" + ry="2.6793056" + rx="1.3412292" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="191.58197" + y="838.75159" + id="text3627"><tspan + sodipodi:role="line" + x="191.58197" + y="838.75159" + style="font-size:22px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans Bold" + id="tspan3631">Parser</tspan><tspan + id="tspan3695" + sodipodi:role="line" + x="191.58197" + y="860.27112" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">parses the</tspan><tspan + id="tspan3697" + sodipodi:role="line" + x="191.58197" + y="880.27112" + style="font-size:16px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;text-anchor:middle;fill:#035800;fill-opacity:1;font-family:Bitstream Vera Sans;-inkscape-font-specification:Bitstream Vera Sans">lib headers</tspan></text> + </g> + <path + sodipodi:nodetypes="ccc" + id="path4056-2-0-1" + d="m 197.39006,961.71122 158.27877,0 0.19429,-51.88885" + style="fill:none;stroke:#000000;stroke-width:1.38812411;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:8.32874408, 1.38812401;stroke-dashoffset:0;marker-start:none" /> + </g> + </g> +</svg> diff --git a/sources/shiboken6/doc/images/icecream.png b/sources/shiboken6/doc/images/icecream.png Binary files differnew file mode 100644 index 000000000..41d1a25fa --- /dev/null +++ b/sources/shiboken6/doc/images/icecream.png diff --git a/sources/shiboken6/doc/images/qtforpython-underthehood.png b/sources/shiboken6/doc/images/qtforpython-underthehood.png Binary files differnew file mode 100644 index 000000000..64e30b1c5 --- /dev/null +++ b/sources/shiboken6/doc/images/qtforpython-underthehood.png diff --git a/sources/shiboken6/doc/images/shibokenqtarch.png b/sources/shiboken6/doc/images/shibokenqtarch.png Binary files differnew file mode 100644 index 000000000..359413373 --- /dev/null +++ b/sources/shiboken6/doc/images/shibokenqtarch.png diff --git a/sources/shiboken6/doc/images/shibokenqtarch.svg b/sources/shiboken6/doc/images/shibokenqtarch.svg new file mode 100644 index 000000000..d9212f18c --- /dev/null +++ b/sources/shiboken6/doc/images/shibokenqtarch.svg @@ -0,0 +1,188 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="275" + height="197.55103" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.92.2 2405546, 2018-03-11" + version="1.0" + sodipodi:docname="shibokenqtarch.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + inkscape:export-filename="shibokenqtarch.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3636" + style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.0474359" + inkscape:cx="110.19617" + inkscape:cy="69.09871" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="true" + inkscape:window-width="1002" + inkscape:window-height="1042" + inkscape:window-x="10" + inkscape:window-y="28" + showguides="true" + inkscape:guide-bbox="true" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + inkscape:window-maximized="0"> + <inkscape:grid + type="xygrid" + id="grid44" + originx="-44.999996" + originy="-12.44898" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-106.0768,-311.50489)"> + <path + style="fill:#21be2b;fill-opacity:1;stroke:none;stroke-width:2.20567369;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 106.0768,322.72938 v 44.89796 h 262.2093 l 12.7907,-11.22449 V 311.50489 H 117.53514 Z" + id="path3715-5-6-7-9-8-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <path + style="fill:#17a81a;fill-opacity:1;stroke:none;stroke-width:1.57079244;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 251.99517,457.61034 v 51.44557 H 369.85231 L 381.0768,498.76679 V 447.32122 H 263.21966 Z" + id="path3715-5-6-7-9-6-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <path + style="fill:#53586b;fill-opacity:1;stroke:none;stroke-width:1.57079256;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 106.0768,457.61034 v 51.44557 h 117.85714 l 11.22449,-10.28912 V 447.32122 H 117.30129 Z" + id="path3715-5-6-7-9-6-7-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:16.68707466px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.12244904;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + x="120.87232" + y="334.88406" + id="text153"><tspan + sodipodi:role="line" + id="tspan151" + x="120.87232" + y="334.88406" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:16.68707466px;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1.12244904;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1">Qt for Python</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.74510956px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:Titillium;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.31862774" + x="121.09701" + y="354.01886" + id="text157"><tspan + sodipodi:role="line" + x="121.09701" + y="354.01886" + id="tspan159" + style="fill:#ffffff;fill-opacity:1;stroke-width:0.31862774">Qt classes and functions exported to Python</tspan></text> + <path + style="fill:#53586b;fill-opacity:1;stroke:none;stroke-width:2.20567369;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 106.0768,391.19877 v 44.89796 h 262.2093 l 12.7907,-11.22449 V 379.97428 H 117.53514 Z" + id="path3715-5-6-7-9-8-7-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:16.68707466px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.41717955" + x="121.0225" + y="403.38095" + id="text153-2"><tspan + sodipodi:role="line" + id="tspan151-9" + x="121.0225" + y="403.38095" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:16.68707466px;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.41717955">Shiboken</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.74510956px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:Titillium;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.31862774" + x="121.09701" + y="421.95245" + id="text157-1"><tspan + sodipodi:role="line" + x="121.09701" + y="421.95245" + id="tspan159-2" + style="fill:#ffffff;fill-opacity:1;stroke-width:0.31862774">Generator that exposes C++ classes to Python</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:17.95918465px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.31862774" + x="123.35368" + y="482.61551" + id="text157-1-7"><tspan + sodipodi:role="line" + x="123.35368" + y="482.61551" + id="tspan159-2-0" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:17.95918465px;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.31862774">CPython API</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:17.95918465px;line-height:1.25;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:0.4132798" + x="265.1445" + y="483.19019" + id="text157-1-9"><tspan + sodipodi:role="line" + x="265.1445" + y="483.19019" + id="tspan159-2-3" + style="font-style:normal;font-variant:normal;font-weight:600;font-stretch:normal;font-size:17.95918465px;font-family:Titillium;-inkscape-font-specification:'Titillium, Semi-Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke-width:0.4132798">Qt 5 Libraries</tspan></text> + </g> +</svg> diff --git a/sources/shiboken6/doc/index.rst b/sources/shiboken6/doc/index.rst new file mode 100644 index 000000000..ebde8d1ff --- /dev/null +++ b/sources/shiboken6/doc/index.rst @@ -0,0 +1,58 @@ +Shiboken +******** + +.. ifconfig:: output_format == 'html' + + Shiboken is a fundamental piece on the `Qt for Python <../index.html>`__ project that serves two purposes: + +.. ifconfig:: output_format == 'qthelp' + + Shiboken is a fundamental piece on the `Qt for Python <../pyside2/index.html>`__ project that serves two purposes: + + +* Generator_: Extract information from C or C++ headers and generate CPython_ code that allow + to bring C or C++ projects to Python. This process uses a library called ApiExtractor_ which + internally uses Clang_. +* Module_: An utility Python module that exposed new Python types, functions to handle pointers, + among other things, that is written in CPython_ and can use independently of the generator. + +.. _Generator: shibokengenerator.html +.. _Module: shibokenmodule.html +.. _CPython: https://github.com/python/cpython +.. _Clang: https://clang.llvm.org/ +.. _ApiExtractor: typesystem.html + +Documentation +============= + +.. raw:: html + + <table class="special"> + <colgroup> + <col style="width: 33%" /> + <col style="width: 33%" /> + <col style="width: 33%" /> + </colgroup> + <tr> + <td><a href="gettingstarted.html"><p><strong>Getting Started</strong><br/>Install and build from source.</p></a></td> + <td><a href="shibokengenerator.html"><p><strong>Shiboken Generator</strong><br/>Binding generator executable.</p></a></td> + <td><a href="shibokenmodule.html"><p><strong>Shiboken Module</strong><br/>Python utility module.</p></a></td> + </tr> + <tr> + <td><a href="typesystem.html"><p><strong>Type System</strong><br/>Reference and functionallities.</p></a></td> + <td><a href="examples/index.html"><p><strong>Examples</strong><br/>Using Shiboken.</p></a></td> + <td><a href="considerations.html"><p><strong>Considerations</strong><br/>Known issues and FAQ.</p></a></td> + </tr> + + </table> + +.. toctree:: + :hidden: + :glob: + + gettingstarted.rst + shibokengenerator.rst + shibokenmodule.rst + typesystem.rst + examples/index.rst + considerations.rst diff --git a/sources/shiboken6/doc/shibokengenerator.rst b/sources/shiboken6/doc/shibokengenerator.rst new file mode 100644 index 000000000..c3000ac09 --- /dev/null +++ b/sources/shiboken6/doc/shibokengenerator.rst @@ -0,0 +1,317 @@ +.. _gen-overview: + +****************** +Generator Overview +****************** + +The following diagram summarizes Shiboken's role in the Qt for Python +project. + +.. image:: images/qtforpython-underthehood.png + +An XML typesystem file is used to specify the types to be exposed to Python +and to apply modifications to properly represent and manipulate the types in +the Python World. For example, you can remove and add methods to certain types, +and also modify the arguments of each method. These actions are inevitable to +properly handle the data structures or types. + +The final outcome of this process is a set of wrappers written in CPython, +which can be used as a module in your Python code. + +In a few words, the Generator is a utility that parses a collection of header and +typesystem files, generating other files (code, documentation, etc.) as result. + +Creating new bindings +===================== + +.. figure:: images/bindinggen-development.png + :scale: 80 + :align: center + + Creating new bindings + +Each module of the generator system has an specific role. + +1. Provide enough data about the classes and functions. +2. Generate valid code, with modifications from typesystems and injected codes. +3. Modify the API to expose the objects in a way that fits you target language best. +4. Insert customizations where handwritten code is needed. + +.. figure:: images/shibokenqtarch.png + :scale: 80 + :align: center + + Runtime architecture + +The newly created binding will run on top of Shiboken which takes +care of interfacing Python and the underlying C++ library. + +Handwritten inputs +================== + +Creating new bindings involves creating two pieces of "code": the typesystem and +the inject code. + +:typesystem: XML files that provides the developer with a tool to customize the + way that the generators will see the classes and functions. For + example, functions can be renamed, have its signature changed and + many other actions. +:inject code: allows the developer to insert handwritten code where the generated + code is not suitable or needs some customization. + +.. _command-line: + +Command line options +******************** + +Usage +----- + +:: + + shiboken [options] header-file(s) typesystem-file + + +Options +------- + +``--disable-verbose-error-messages`` + Disable verbose error messages. Turn the CPython code hard to debug but saves a few kilobytes + in the generated binding. + +.. _parent-heuristic: + +``--enable-parent-ctor-heuristic`` + This flag enable an useful heuristic which can save a lot of work related to object ownership when + writing the typesystem. + For more info, check :ref:`ownership-parent-heuristics`. + +.. _pyside-extensions: + +``--enable-pyside-extensions`` + Enable pyside extensions like support for signal/slots. Use this if you are creating a binding based + on PySide. + +.. _return-heuristic: + +``--enable-return-value-heuristic`` + Enable heuristics to detect parent relationship on return values. + For more info, check :ref:`return-value-heuristics`. + +.. _avoid-protected-hack: + +``--avoid-protected-hack`` + Avoid the use of the '#define protected public' hack. + +.. _use-isnull-as-nb_nonzero: + +``--use-isnull-as-nb_nonzero`` + If a class have an isNull() const method, it will be used to + compute the value of boolean casts + +.. _api-version: + +``--api-version=<version>`` + Specify the supported api version used to generate the bindings. + +.. _documentation-only: + +``--documentation-only`` + Do not generate any code, just the documentation. + +.. _drop-type-entries: + +``--drop-type-entries="<TypeEntry0>[;TypeEntry1;...]"`` + Semicolon separated list of type system entries (classes, namespaces, + global functions and enums) to be dropped from generation. Values are + fully qualified Python type names ('Module.Class'), but the module can + be omitted ('Class'). + +.. _generation-set: + +``--generation-set`` + Generator set to be used (e.g. qtdoc). + +.. _skip-deprecated: + +``--skip-deprecated`` + Skip deprecated functions. + +.. _diff: + +``--diff`` + Print a diff of wrapper files. + +.. _dryrun: + +``--dryrun`` + Dry run, do not generate wrapper files. + +.. _--project-file: + +``--project-file=<file>`` + Text file containing a description of the binding project. + Replaces and overrides command line arguments. + +.. _include-paths: + +``-I<path>, --include-paths=<path>[:<path>:...]`` + Include paths used by the C++ parser. + +... _system-include-paths: + +``-isystem<path>, --system-include-paths=<path>[:<path>:...]`` + System include paths used by the C++ parser + +.. _framework-include-paths: + +``-F<path>, --framework-include-paths=<path>[:<path>:...]`` + Framework include paths used by the C++ parser + +.. _language-level: + +``--language-level=, -std=<level>`` + C++ Language level (c++11..c++17, default=c++14) + +.. _typesystem-paths: + +``-T<path>, --typesystem-paths=<path>[:<path>:...]`` + Paths used when searching for type system files. + +.. _output-directory: + +``--output-directory=[dir]`` + The directory where the generated files will be written. + +.. _license-file=[license-file]: + +``--license-file=[license-file]`` + File used for copyright headers of generated files. + +.. _no-suppress-warnings: + +``--no-suppress-warnings`` + Show all warnings. + +.. _silent: + +``--silent`` + Avoid printing any message. + +.. _debug-level: + +``--debug-level=[sparse|medium|full]`` + Set the debug level. + +.. _help: + +``--help`` + Display this help and exit. + +.. _version: + +``--version`` + Output version information and exit. + +QtDocGenerator Options +---------------------- + +.. _doc-parser: + +``--doc-parser=<parser>`` + The documentation parser used to interpret the documentation + input files (qdoc|doxygen). + +.. _documentation-code-snippets-dir: + +``--documentation-code-snippets-dir=<dir>`` + Directory used to search code snippets used by the documentation. + +.. _documentation-data-dir: + +``--documentation-data-dir=<dir>`` + Directory with XML files generated by documentation tool. + +.. _documentation-extra-sections-dir=<dir>: + +``--documentation-extra-sections-dir=<dir>`` + Directory used to search for extra documentation sections. + +.. _library-source-dir: + +``--library-source-dir=<dir>`` + Directory where library source code is located. + +.. _additional-documentation: + +``--additional-documentation=<file>`` + List of additional XML files to be converted to .rst files + (for example, tutorials). + +.. _project-file: + +******************** +Binding Project File +******************** + +Instead of directing the Generator behavior via command line, the binding +developer can write a text project file describing the same information, and +avoid the hassle of a long stream of command line arguments. + +.. _project-file-structure: + +The project file structure +========================== + +Here follows a comprehensive example of a generator project file. + + .. code-block:: ini + + [generator-project] + generator-set = path/to/generator/CHOICE_GENERATOR + header-file = DIR/global.h" /> + typesystem-file = DIR/typesystem_for_your_binding.xml + output-directory location="OUTPUTDIR" /> + include-path = path/to/library/being/wrapped/headers/1 + include-path = path/to/library/being/wrapped/headers/2 + typesystem-path = path/to/directory/containing/type/system/files/1 + typesystem-path = path/to/directory/containing/type/system/files/2 + enable-parent-ctor-heuristic + + +Project file tags +================= + +The generator project file tags are in direct relation to the +:ref:`command line arguments <command-line>`. All of the current command line +options provided by |project| were already seen on the +:ref:`project-file-structure`, for new command line options provided by +additional generator modules (e.g.: qtdoc, Shiboken) could also be used in the +generator project file following simple conversion rules. + +For tags without options, just write as an empty tag without any attributes. +Example: + + .. code-block:: bash + + --BOOLEAN-ARGUMENT + +becomes + + .. code-block:: ini + + BOOLEAN-ARGUMENT + +and + + .. code-block:: bash + + --VALUE-ARGUMENT=VALUE + +becomes + + .. code-block:: ini + + VALUE-ARGUMENT = VALUE + + diff --git a/sources/shiboken6/doc/shibokenmodule.rst b/sources/shiboken6/doc/shibokenmodule.rst new file mode 100644 index 000000000..150998ccd --- /dev/null +++ b/sources/shiboken6/doc/shibokenmodule.rst @@ -0,0 +1,79 @@ +.. module:: shiboken + +.. |maya| unicode:: Maya U+2122 + +Shiboken module +*************** + +Functions +^^^^^^^^^ + +.. container:: function_list + + * def :meth:`isValid<shiboken.isValid>` (obj) + * def :meth:`wrapInstance<shiboken.wrapInstance>` (address, type) + * def :meth:`getCppPointer<shiboken.getCppPointer>` (obj) + * def :meth:`delete<shiboken.delete>` (obj) + * def :meth:`isOwnedByPython<shiboken.isOwnedByPython>` (obj) + * def :meth:`wasCreatedByPython<shiboken.wasCreatedByPython>` (obj) + * def :meth:`dump<shiboken.dump>` (obj) + +Detailed description +^^^^^^^^^^^^^^^^^^^^ + +This Python module can be used to access internal information related to our +binding technology. Access to this internal information is required to e.g.: +integrate PySide with Qt based programs that offer Python scripting like |maya| +or just for debug purposes. + +Some function description refer to "Shiboken based objects", wich means +Python objects instances of any Python Type created using Shiboken. + + +.. function:: isValid(obj) + + Given a Python object, returns True if the object methods can be called + without an exception being thrown. A Python wrapper becomes invalid when + the underlying C++ object is destroyed or unreachable. + +.. function:: wrapInstance(address, type) + + Creates a Python wrapper for a C++ object instantiated at a given memory + address - the returned object type will be the same given by the user. + + The type must be a Shiboken type, the C++ object will not be + destroyed when the returned Python object reach zero references. + + If the address is invalid or doesn't point to a C++ object of given type + the behavior is undefined. + +.. function:: getCppPointer(obj) + + Returns a tuple of longs that contain the memory addresses of the + C++ instances wrapped by the given object. + +.. function:: delete(obj) + + Deletes the C++ object wrapped by the given Python object. + +.. function:: isOwnedByPython(obj) + + Given a Python object, returns True if Python is responsible for deleting + the underlying C++ object, False otherwise. + + If the object was not a Shiboken based object, a TypeError is + thrown. + +.. function:: wasCreatedByPython(obj) + + Returns true if the given Python object was created by Python. + +.. function:: dump(obj) + + Returns a string with implementation-defined information about the + object. + This method should be used **only** for debug purposes by developers + creating their own bindings as no guarantee is provided that + the string format will be the same across different versions. + + If the object is not a Shiboken based object, a TypeError is thrown. diff --git a/sources/shiboken6/doc/typesystem.rst b/sources/shiboken6/doc/typesystem.rst new file mode 100644 index 000000000..0d43cec2c --- /dev/null +++ b/sources/shiboken6/doc/typesystem.rst @@ -0,0 +1,65 @@ +Type System Reference +===================== + +The typesystem is used by a binding generator or any other software using the APIExtractor library +to map a C++ library API onto a higher level language. + +The typesystem specification is a handwritten XML document listing the types +that will be available in the generated target language API; types that are not +declared in the specification will be ignored along with everything depending on +them. In addition, it is possible to manipulate and modify types and functions. +It is even possible to use the typesystem specification to inject arbitrary +code into the source files, such as an extra member function. + +Below there is a complete reference guide to the various nodes (XML tags) of the typesystem. +For usage examples, take a look at the typesystem files used to generate PySide2. These files +can be found in the PySide2/<QT_MODULE_NAME> directory of the PySide2 package. + +Define types +------------ + +.. toctree:: + :maxdepth: 1 + + typesystem_specifying_types.rst + +Code generation +--------------- + +.. toctree:: + :maxdepth: 1 + + typesystem_codegeneration.rst + +Modifying types +--------------- + +.. toctree:: + :maxdepth: 1 + + typesystem_arguments.rst + typesystem_codeinjection.rst + typesystem_converters.rst + typesystem_templates.rst + typesystem_modify_function.rst + typesystem_manipulating_objects.rst + typesystem_conversionrule.rst + typesystem_documentation.rst + typesystem_variables.rst + +Object ownership +---------------- + +.. toctree:: + :maxdepth: 1 + + typesystem_ownership.rst + +Extra options and Python caveats +-------------------------------- + +.. toctree:: + :maxdepth: 1 + + typesystem_solving_compilation.rst + typesystem_sequenceprotocol.rst diff --git a/sources/shiboken6/doc/typesystem_arguments.rst b/sources/shiboken6/doc/typesystem_arguments.rst new file mode 100644 index 000000000..bce0914e3 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_arguments.rst @@ -0,0 +1,207 @@ +.. _modifying-arguments: + +Modifying Arguments +------------------- + +.. _conversionrule: + +conversion-rule +^^^^^^^^^^^^^^^ + + The conversion-rule node allows you to write customized code to convert + the given argument between the target language and C++, and it is a child of the modify-argument node: + + .. code-block:: xml + + <modify-argument index="2"> + <!-- for the second argument of the function --> + <conversion-rule class="target | native"> + // the code + </conversion-rule> + </modify-argument> + + This node is typically used in combination with the replace-type and + remove-argument nodes. The given code is used instead of the generator's + conversion code. + + Writing %N in the code (where N is a number), will insert the name of the + nth argument. Alternatively, %in and %out which will be replaced with the + name of the conversion's input and output variable, respectively. Note the + output variable must be declared explicitly, for example: + + .. code-block:: xml + + <conversion-rule class="native"> + bool %out = (bool) %in; + </conversion-rule> + + .. note:: You can also use the conversion-rule node to specify :ref:`a conversion code which will be used instead of the generator's conversion code everywhere for a given type <conversion-rule-on-types>`. + +.. _remove-argument: + +remove-argument +^^^^^^^^^^^^^^^ + + The remove-argument node removes the given argument from the function's + signature, and it is a child of the modify-argument node. + + .. code-block:: xml + + <modify-argument> + <remove-argument /> + </modify-argument> + +.. _rename-to: + +rename to +^^^^^^^^^ + + The 'rename to' node is used to rename a argument and use this new name in the generated code. + + .. code-block:: xml + + <modify-argument> + <rename to='...' /> + </modify-argument> + +.. _remove-default-expression: + +remove-default-expression +^^^^^^^^^^^^^^^^^^^^^^^^^ + + The remove-default-expression node disables the use of the default expression + for the given argument, and it is a child of the modify-argument node. + + .. code-block:: xml + + <modify-argument...> + <remove-default-expression /> + </modify-argument> + +.. _replace-default-expression: + +replace-default-expression +^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The replace-default-expression node replaces the specified argument with the + expression specified by the ``with`` attribute, and it is a child of the + modify-argument node. + + .. code-block:: xml + + <modify-argument> + <replace-default-expression with="..." /> + </modify-argument> + +.. _replace-type: + +replace-type +^^^^^^^^^^^^ + + The replace-type node replaces the type of the given argument to the one + specified by the ``modified-type`` attribute, and it is a child of the + modify-argument node. + + .. code-block:: xml + + <modify-argument> + <replace-type modified-type="..." /> + </modify-argument> + + If the new type is a class, the ``modified-type`` attribute must be set to + the fully qualified name (including name of the package as well as the class + name). + +.. _define-ownership: + +define-ownership +^^^^^^^^^^^^^^^^ + + The define-ownership tag indicates that the function changes the ownership + rules of the argument object. The ``class`` attribute specifies the class of + function where to inject the ownership altering code + (see :ref:`codegenerationterminology`). The ``owner`` attribute + specifies the new ownership of the object. It accepts the following values: + + * target: the target language will assume full ownership of the object. + The native resources will be deleted when the target language + object is finalized. + * c++: The native code assumes full ownership of the object. The target + language object will not be garbage collected. + * default: The object will get default ownership, depending on how it + was created. + + .. code-block:: xml + + <modify-argument> + <define-ownership class="target | native" + owner="target | c++ | default" /> + </modify-argument> + +.. _reference-count: + +reference-count +^^^^^^^^^^^^^^^ + + The reference-count tag dictates how an argument should be handled by the + target language reference counting system (if there is any), it also indicates + the kind of relationship the class owning the function being modified has with + the argument. For instance, in a model/view relation a view receiving a model + as argument for a **setModel** method should increment the model's reference + counting, since the model should be kept alive as much as the view lives. + Remember that out hypothetical view could not become parent of the model, + since the said model could be used by other views as well. + The ``action`` attribute specifies what should be done to the argument + reference counting when the modified method is called. It accepts the + following values: + + * add: increments the argument reference counter. + * add-all: increments the reference counter for each item in a collection. + * remove: decrements the argument reference counter. + * set: will assign the argument to the variable containing the reference. + * ignore: does nothing with the argument reference counter + (sounds worthless, but could be used in situations + where the reference counter increase is mandatory + by default). + + .. code-block:: xml + + <modify-argument> + <reference-count action="add|add-all|remove|set|ignore" variable-name="..." /> + </modify-argument> + + + The variable-name attribute specifies the name used for the variable that + holds the reference(s). + +.. _replace-value: + +replace-value +^^^^^^^^^^^^^ + + The ``replace-value`` attribute lets you replace the return statement of a + function with a fixed string. This attribute can only be used for the + argument at ``index`` 0, which is always the function's return value. + + .. code-block:: xml + + <modify-argument index="0" replace-value="this"/> + +.. _parent: + +parent +^^^^^^ + + The parent node lets you define the argument parent which will + take ownership of argument and will destroy the C++ child object when the + parent is destroyed. + + .. code-block:: xml + + <modify-argument index="1"> + <parent index="this" action="add | remove" /> + </modify-argument> + + In the ``index`` argument you must specify the parent argument. The action + *add* creates a parent link between objects, while *remove* will undo the + parentage relationship. diff --git a/sources/shiboken6/doc/typesystem_codegeneration.rst b/sources/shiboken6/doc/typesystem_codegeneration.rst new file mode 100644 index 000000000..fb41e28e1 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_codegeneration.rst @@ -0,0 +1,37 @@ +.. _codegenerationterminology: + +*************************** +Code Generation Terminology +*************************** + +Types of generated code +======================= + + +**Python Wrapper** + The code that exports the C++ wrapped class to Python. **Python wrapper** + refers to all the code needed to export a C++ class to Python, and + **Python method/function wrapper** means the specific function that calls + the C++ method/function on behalf of Python. This code is invoked from + the Python side. + +**C++ Wrapper** + This term refers to a generated C++ class that extends a class from the + wrapped library. It is generated only when a wrapped C++ class is + polymorphic, i.e. it has or inherits any virtual methods. + The **C++ Wrapper** overrides the virtual methods of the wrapped C++ class + with code that allows for overriding the method with a Python implementation. + It checks whether a corresponding method in the Python instance exists and + calls it. This code is invoked from the C++ side. + + +Specifying a target for modifications +===================================== + +In the typesystem files, the ``class`` attribute is used to which class a +modification is applied (see :ref:`codeinjectionsemantics`, +:ref:`objectownership`). +The value **Target** means the modification is applied to the +**Python Wrapper**. The value **Native** means the modification is applied to +the **C++ Wrapper**. + diff --git a/sources/shiboken6/doc/typesystem_codeinjection.rst b/sources/shiboken6/doc/typesystem_codeinjection.rst new file mode 100644 index 000000000..b0d5f3851 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_codeinjection.rst @@ -0,0 +1,390 @@ +.. _codeinjectionsemantics: + +************************ +Code Injection Semantics +************************ + +:std:doc:`API Extractor <shibokengenerator>` provides the +:ref:`inject-code <inject-code>` tag +allowing the user to put custom written code to on specific locations of the generated code. +Yet this is only part of what is needed to generate proper binding code, where the custom code +should be written to depends upon the technology used on the generated binding code. + +This is the ``inject-code`` tag options that matters to |project|. + + .. code-block:: xml + + <inject-code class="native | target" position="beginning | end"> + // custom code + </inject-code> + + +inject-code tag +=============== + +The following table describes the semantics of ``inject-code`` tag as used on +|project|. The ``class`` attribute specifies whether to code is injected +into the **C++ Wrapper** or the **Python Wrapper** (see +:ref:`codegenerationterminology`). +The ``position`` attribute specifies the location of the custom code in the +function. + + + +---------------+------+-----------+--------------------------------------------------------------+ + |Parent Tag |Class |Position |Meaning | + +===============+======+===========+==============================================================+ + |value-type, |native|beginning |Write to the beginning of a class wrapper ``.cpp`` file, right| + |object-type | | |after the ``#include`` clauses. A common use would be to write| + | | | |prototypes for custom functions whose definitions are put on a| + | | | |``native/end`` code injection. | + | | +-----------+--------------------------------------------------------------+ + | | |end |Write to the end of a class wrapper ``.cpp`` file. Could be | + | | | |used to write custom/helper functions definitions for | + | | | |prototypes declared on ``native/beginning``. | + | +------+-----------+--------------------------------------------------------------+ + | |target|beginning |Put custom code on the beginning of the wrapper initializer | + | | | |function (``init_CLASS(PyObject *module)``). This could be | + | | | |used to manipulate the ``PyCLASS_Type`` structure before | + | | | |registering it on Python. | + | | +-----------+--------------------------------------------------------------+ + | | |end |Write the given custom code at the end of the class wrapper | + | | | |initializer function (``init_CLASS(PyObject *module)``). The | + | | | |code here will be executed after all the wrapped class | + | | | |components have been initialized. | + +---------------+------+-----------+--------------------------------------------------------------+ + |modify-function|native|beginning |Code here is put on the virtual method override of a C++ | + | | | |wrapper class (the one responsible for passing C++ calls to a | + | | | |Python override, if there is any), right after the C++ | + | | | |arguments have been converted but before the Python call. | + | | +-----------+--------------------------------------------------------------+ + | | |end |This code injection is put in a virtual method override on the| + | | | |C++ wrapper class, after the call to Python and before | + | | | |dereferencing the Python method and tuple of arguments. | + | +------+-----------+--------------------------------------------------------------+ + | |target|beginning |This code is injected on the Python method wrapper | + | | | |(``PyCLASS_METHOD(...)``), right after the decisor have found | + | | | |which signature to call and also after the conversion of the | + | | | |arguments to be used, but before the actual call. | + | | +-----------+--------------------------------------------------------------+ + | | |end |This code is injected on the Python method wrapper | + | | | |(``PyCLASS_METHOD(...)``), right after the C++ method call, | + | | | |but still inside the scope created by the overload for each | + | | | |signature. | + | +------+-----------+--------------------------------------------------------------+ + | |shell |declaration|Used only for virtual functions. This code is injected at the | + | | | |top. | + | | +-----------+--------------------------------------------------------------+ + | | |beginning |Used only for virtual functions. The code is injected when the| + | | | |function does not has a Python implementation, then the code | + | | | |is inserted before c++ call | + | | +-----------+--------------------------------------------------------------+ + | | |end |Same as above, but the code is inserted after c++ call | + +---------------+------+-----------+--------------------------------------------------------------+ + |typesystem |native|beginning |Write code to the beginning of the module ``.cpp`` file, right| + | | | |after the ``#include`` clauses. This position has a similar | + | | | |purpose as the ``native/beginning`` position on a wrapper | + | | | |class ``.cpp`` file, namely write function prototypes, but not| + | | | |restricted to this use. | + | | +-----------+--------------------------------------------------------------+ + | | |end |Write code to the end of the module ``.cpp`` file. Usually | + | | | |implementations for function prototypes inserted at the | + | | | |beginning of the file with a ``native/beginning`` code | + | | | |injection. | + | +------+-----------+--------------------------------------------------------------+ + | |target|beginning |Insert code at the start of the module initialization function| + | | | |(``initMODULENAME()``), before the calling ``Py_InitModule``. | + | | +-----------+--------------------------------------------------------------+ + | | |end |Insert code at the end of the module initialization function | + | | | |(``initMODULENAME()``), but before the checking that emits a | + | | | |fatal error in case of problems importing the module. | + | | +-----------+--------------------------------------------------------------+ + | | |declaration|Insert code into module header. | + +---------------+------+-----------+--------------------------------------------------------------+ + + +Anatomy of Code Injection +========================= + +To make things clear let's use a simplified example of generated wrapper code +and the places where each kind of code injection goes. + +Below is the example C++ class for whom wrapper code will be generated. + + .. code-block:: c++ + + class InjectCode { + public: + InjectCode(); + double overloadedMethod(int arg); + double overloadedMethod(double arg); + virtual int virtualMethod(int arg); + }; + +From the C++ class, |project| will generate a ``injectcode_wrapper.cpp`` file +with the binding code. The next section will use a simplified version of the +generated wrapper code with the injection spots marked with comments. + +Noteworthy Cases +---------------- + +The type system description system gives the binding developer a lot of +flexibility, which is power, which comes with responsibility. Some modifications +to the wrapped API will not be complete without some code injection. + + +Removing arguments and setting a default values for them +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A simple case is when a function have one argument removed, as when the C++ +method ``METHOD(ARG)`` is modified to be used from Python as ``METHOD()``; +of course the binding developer must provide some guidelines to the generator +on what to do to call it. The most common solution is to remove the argument and +set a default value for it at the same time, so the original C++ method could be +called without problems. + +Removing arguments and calling the method with your own hands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the argument is removed and no default value is provided, the generator will +not write any call to the method and expect the ``modify-function - target/beginning`` +code injection to call the original C++ method on its own terms. If even this +custom code is not provided the generator will put an ``#error`` clause to +prevent compilation of erroneous binding code. + +Calling the method with your own hands always! +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If your custom code to be injected contains a call to the wrapped C++ method, +it surely means that you don't want the generator to write another call to the +same method. As expected |project| will detect the user written call on the code +injection and will not write its own call, but for this to work properly the +binding developer must use the template variable ``%FUNCTION_NAME`` instead +of writing the actual name of the wrapped method/function. + +In other words, use + + .. code-block:: xml + + <inject-code class="target" position="beginning | end"> + %CPPSELF.originalMethodName(); + </inject-code> + + +instead of + + + .. code-block:: xml + + <inject-code class="target" position="beginning | end"> + %CPPSELF.%FUNCTION_NAME(); + </inject-code> + + +Code Injection for Functions/Methods +==================================== + + +.. _codeinjecting_method_native: + +On The Native Side +------------------ + +Notice that this is only used when there is a C++ wrapper, i.e. the wrapped +class is polymorphic. + + .. code-block:: c++ + + int InjectCodeWrapper::virtualMethod(int arg) + { + PyObject* method = BindingManager::instance().getOverride(this, "virtualMethod"); + if (!py_override) + return this->InjectCode::virtualMethod(arg); + + (... here C++ arguments are converted to Python ...) + + // INJECT-CODE: <modify-function><inject-code class="native" position="beginning"> + // Uses: pre method call custom code, modify the argument before the + // Python call. + + (... Python method call goes in here ...) + + // INJECT-CODE: <modify-function><inject-code class="native" position="end"> + // Uses: post method call custom code, modify the result before delivering + // it to C++ caller. + + (... Python method and argument tuple are dereferenced here ...) + + return Shiboken::Converter<int>::toCpp(method_result); + } + + +On The Target Side +------------------ + +All the overloads of a method from C++ are gathered together on a single Python +method that uses an overload decisor to call the correct C++ method based on the +arguments passed by the Python call. Each overloaded method signature has its +own ``beginning`` and ``end`` code injections. + + .. code-block:: c++ + + static PyObject* + PyInjectCode_overloadedMethod(PyObject* self, PyObject* arg) + { + PyObject* py_result = 0; + if (PyFloat_Check(arg)) { + double cpp_arg0 = Shiboken::Converter<double >::toCpp(arg); + + // INJECT-CODE: <modify-function><inject-code class="target" position="beginning"> + // Uses: pre method call custom code. + + py_result = Shiboken::Converter<double >::toPython( + PyInjectCode_cptr(self)->InjectCode::overloadedMethod(cpp_arg0) + ); + + // INJECT-CODE: <modify-function><inject-code class="target" position="end"> + // Uses: post method call custom code. + + } else if (PyNumber_Check(arg)) { + (... other overload calling code ...) + } else goto PyInjectCode_overloadedMethod_TypeError; + + if (PyErr_Occurred() || !py_result) + return 0; + + return py_result; + + PyInjectCode_overloadedMethod_TypeError: + PyErr_SetString(PyExc_TypeError, "'overloadedMethod()' called with wrong parameters."); + return 0; + } + + +.. _codeinjecting_classes: + +Code Injection for Wrapped Classes +================================== + +.. _codeinjecting_classes_native: + +On The Native Side +------------------ + +Those injections go in the body of the ``CLASSNAME_wrapper.cpp`` file for the +wrapped class. + + .. code-block:: c++ + + // Start of ``CLASSNAME_wrapper.cpp`` + #define protected public + // default includes + #include <shiboken.h> + (...) + #include "injectcode_wrapper.h" + using namespace Shiboken; + + // INJECT-CODE: <value/object-type><inject-code class="native" position="beginning"> + // Uses: prototype declarations + + (... C++ wrapper virtual methods, if any ...) + + (... Python wrapper code ...) + + PyAPI_FUNC(void) + init_injectcode(PyObject *module) + { + (...) + } + + (...) + + // INJECT-CODE: <value/object-type><inject-code class="native" position="end"> + // Uses: definition of functions prototyped at ``native/beginning``. + + // End of ``CLASSNAME_wrapper.cpp`` + + +.. _codeinjecting_classes_target: + +On The Target Side +------------------ + +Code injections to the class Python initialization function. + + .. code-block:: c++ + + // Start of ``CLASSNAME_wrapper.cpp`` + + (...) + + PyAPI_FUNC(void) + init_injectcode(PyObject *module) + { + // INJECT-CODE: <value/object-type><inject-code class="target" position="beginning"> + // Uses: Alter something in the PyInjectCode_Type (tp_flags value for example) + // before registering it. + + if (PyType_Ready(&PyInjectCode_Type) < 0) + return; + + Py_INCREF(&PyInjectCode_Type); + PyModule_AddObject(module, "InjectCode", + ((PyObject*)&PyInjectCode_Type)); + + // INJECT-CODE: <value/object-type><inject-code class="target" position="end"> + // Uses: do something right after the class is registered, like set some static + // variable injected on this same file elsewhere. + } + + (...) + + // End of ``CLASSNAME_wrapper.cpp`` + +Code Injection for Modules +========================== + +The C++ libraries are wrapped as Python modules, a collection of classes, +functions, enums and namespaces. |project| creates wrapper files for all of +them and also one extra ``MODULENAME_module_wrapper.cpp`` to register the whole +module. Code injection xml tags who have the ``typesystem`` tag as parent will +be put on this file. + +On The Native Side +------------------ + +This works exactly as the class wrapper code injections :ref:`codeinjecting_classes_native`. + +On The Target Side +------------------ + +This is very similar to class wrapper code injections :ref:`codeinjecting_classes_target`. +Notice that the inject code at ``target/end`` is inserted before the check for errors +to prevent bad custom code to pass unnoticed. + + .. code-block:: c++ + + // Start of ``MODULENAME_module_wrapper.cpp`` + + (...) + initMODULENAME() + { + // INJECT-CODE: <typesystem><inject-code class="target" position="beginning"> + // Uses: do something before the module is created. + + PyObject* module = Py_InitModule("MODULENAME", MODULENAME_methods); + + (... initialization of wrapped classes, namespaces, functions and enums ...) + + // INJECT-CODE: <typesystem><inject-code class="target" position="end"> + // Uses: do something after the module is registered and initialized. + + if (PyErr_Occurred()) + Py_FatalError("can't initialize module sample"); + } + + (...) + + // Start of ``MODULENAME_module_wrapper.cpp`` + +In addition, code can be injected into the module header by specifying ``target`` +and ``declaration``. This is useful for type definitions. diff --git a/sources/shiboken6/doc/typesystem_conversionrule.rst b/sources/shiboken6/doc/typesystem_conversionrule.rst new file mode 100644 index 000000000..27e7a72de --- /dev/null +++ b/sources/shiboken6/doc/typesystem_conversionrule.rst @@ -0,0 +1,116 @@ +.. _conversion-rule-tag: + +Conversion Rule Tag +------------------- + +.. _conversion-rule: + +conversion-rule +^^^^^^^^^^^^^^^ + + The **conversion-rule** tag specifies how a **primitive-type**, a **container-type**, + or a **value-type** may be converted to and from the native C++ language types to the + target language types. + + .. code-block:: xml + + <value-type> + <conversion-rule> + <native-to-target> + // Code to convert a native value to a target language object. + </native-to-target> + <target-to-native> + <add-conversion type='TARGETTYPEA' check='TARGETTYPEA_CHECK(%in)'> + // Code to convert target language type object of type TARGETTYPEA + // to the C++ native type represented by the value/primitive/container-type. + </add-conversion> + <add-conversion type='TARGETTYPEB' check='TARGETTYPEB_CHECK(%in)'> + // Code to convert target language type object of type TARGETTYPEB + // to the C++ native type represented by the value/primitive/container-type. + </add-conversion> + </target-to-native> + </conversion-rule> + </value-type> + + The example above show the structure of a complete conversion rule. Each of the + child tags comprising the conversion rule are described in their own sections + below. + + +.. _native-to-target: + +native-to-target +^^^^^^^^^^^^^^^^ + + The **native-to-target** tag tells how to convert a native C++ value to its + target language equivalent. The text inside the tag is a C++ code the takes + an input value an does what's needed to convert it to the output value. + ``insert-template`` tags may be used to insert commonly repeating code. + + .. code-block:: xml + + <conversion-rule> + <native-to-target> + // Code to convert a native value to a target language object. + </native-to-target> + </conversion-rule> + + Use the replace node to modify the template code. + Notice that the generator must provide type system variables for the input + and output values and types, namely **%in**, **%out**, **%INTYPE** and + **%OUTTYPE**. In the case of container types, **%INTYPE** refers to the + full container type (e.g. **"list<int>"**) and **%INTYPE_0**, **%INTYPE_1**, + **%INTYPE_#**, should be replaced by the types used in the container template + (e.g. **%INTYPE_0** correspondes to **"int"** for **"list<int>"**). + + The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes). + +.. _target-to-native: + +target-to-native +^^^^^^^^^^^^^^^^ + + The **target-to-native** tag encloses at least one, but usually many, conversions + from target language values to C++ native values. The *optional* attribute + ``replace`` tells if the target language to C++ conversions will be added to, or if + they will replace the implicit conversions collected by *ApiExtractor*. The default + value for it is *yes*. + + + .. code-block:: xml + + <conversion-rule> + <target-to-native replace='yes|no'>\ + // List of target to native conversions meant to replace or expand + // the already existing implicit conversions. + </target-to-native> + </conversion-rule> + + +.. _add-conversion: + +add-conversion +^^^^^^^^^^^^^^ + + Each **add-conversion** tag adds a rule for conversion of a target language type, + indicated by the ``type`` attribute, to the C++ native type represented by the + **primitive-type**, a **container-type**, or **value-type**, to which the parent + **conversion-rule** belongs. + + .. code-block:: xml + + <target-to-native> + <add-conversion type='TARGETTYPE' check='TARGETTYPECHECK(%in)'> + // Code to convert target language type object of type TARGETTYPE_A + // to the C++ native type represented by the value/primitive/container-type. + </add-conversion> + <target-to-native> + + The ``check`` attribute tells how a target value should be checked to see if it belongs to + the type expected. This attribute is *optional*, for it can be derived from the ``type`` + attribute, but it isn't unusual that some special check is needed. The variables + **%in**, **%out**, **%INTYPE**, **%INTYPE_#**, and **%OUTTYPE**, must be provided by + the generator as in the ``native-to-target`` tag. + + The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes). + diff --git a/sources/shiboken6/doc/typesystem_converters.rst b/sources/shiboken6/doc/typesystem_converters.rst new file mode 100644 index 000000000..872daa187 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_converters.rst @@ -0,0 +1,291 @@ +**************************** +User Defined Type Conversion +**************************** + +In the process of creating Python bindings of a C++ library, most of the C++ +classes will have wrappers representing them in Python land. +But there may be other classes that are very simple and/or have a Python type +as a direct counter part. (Example: a "Complex" class, that represents complex +numbers, has a Python equivalent in the "complex" type.) Such classes, instead +of getting a Python wrapper, normally have conversions rules, from Python to +C++ and vice-versa. + + .. code-block:: c++ + + // C++ class + struct Complex { + Complex(double real, double imag); + double real() const; + double imag() const; + }; + + // Converting from C++ to Python using the CPython API: + PyObject* pyCpxObj = PyComplex_FromDoubles(complex.real(), complex.imag()); + + // Converting from Python to C++: + double real = PyComplex_RealAsDouble(pyCpxObj); + double imag = PyComplex_ImagAsDouble(pyCpxObj); + Complex cpx(real, imag); + + +For the user defined conversion code to be inserted in the proper places, +the "<conversion-rule>" tag must be used. + + .. code-block:: xml + + <primitive-type name="Complex" target-lang-api-name="PyComplex"> + <include file-name="complex.h" location="global"/> + + <conversion-rule> + + <native-to-target> + return PyComplex_FromDoubles(%in.real(), %in.imag()); + </native-to-target> + + <target-to-native> + <!-- The 'check' attribute can be derived from the 'type' attribute, + it is defined here to test the CHECKTYPE type system variable. --> + <add-conversion type="PyComplex" check="%CHECKTYPE[Complex](%in)"> + double real = PyComplex_RealAsDouble(%in); + double imag = PyComplex_ImagAsDouble(%in); + %out = %OUTTYPE(real, imag); + </add-conversion> + </target-to-native> + + </conversion-rule> + + </primitive-type> + + +The details will be given later, but the gist of it are the tags +:ref:`native-to-target <native-to-target>`, which has only one conversion from C++ to Python, and +:ref:`native-to-native <target-to-native>`, that may define the conversion of multiple Python types +to C++'s "Complex" type. + +.. image:: images/converter.png + :height: 240px + :align: center + +|project| expects the code for :ref:`native-to-target <native-to-target>`, to directly return the +Python result of the conversion, and the added conversions inside the +:ref:`target-to-native <target-to-native>` must attribute the Python to C++ conversion result to +the :ref:`%out <out>` variable. + +Expanding on the last example, if the binding developer want a Python 2-tuple +of numbers to be accepted by wrapped C++ functions with "Complex" arguments, +an :ref:`add-conversion <add-conversion>` tag and a custom check must be added. +Here's how to do it: + + .. code-block:: xml + + <!-- Code injection at module level. --> + <inject-code class="native" position="beginning"> + static bool Check2TupleOfNumbers(PyObject* pyIn) { + if (!PySequence_Check(pyIn) || !(PySequence_Size(pyIn) == 2)) + return false; + Shiboken::AutoDecRef pyReal(PySequence_GetItem(pyIn, 0)); + if (!SbkNumber_Check(pyReal)) + return false; + Shiboken::AutoDecRef pyImag(PySequence_GetItem(pyIn, 1)); + if (!SbkNumber_Check(pyImag)) + return false; + return true; + } + </inject-code> + + <primitive-type name="Complex" target-lang-api-name="PyComplex"> + <include file-name="complex.h" location="global"/> + + <conversion-rule> + + <native-to-target> + return PyComplex_FromDoubles(%in.real(), %in.imag()); + </native-to-target> + + <target-to-native> + + <add-conversion type="PyComplex"> + double real = PyComplex_RealAsDouble(%in); + double imag = PyComplex_ImagAsDouble(%in); + %out = %OUTTYPE(real, imag); + </add-conversion> + + <add-conversion type="PySequence" check="Check2TupleOfNumbers(%in)"> + Shiboken::AutoDecRef pyReal(PySequence_GetItem(%in, 0)); + Shiboken::AutoDecRef pyImag(PySequence_GetItem(%in, 1)); + double real = %CONVERTTOCPP[double](pyReal); + double imag = %CONVERTTOCPP[double](pyImag); + %out = %OUTTYPE(real, imag); + </add-conversion> + + </target-to-native> + + </conversion-rule> + + </primitive-type> + + +.. _container_conversions: + +Container Conversions +===================== + +Converters for :ref:`container-type <container-type>` are pretty much the same as for other type, +except that they make use of the type system variables +:ref:`%INTYPE_# <intype_n>` and :ref:`%OUTTYPE_# <outtype_n>`. +|project| combines the conversion code for containers with the conversion +defined (or automatically generated) for the containers. + + .. code-block:: xml + + <container-type name="std::map" type="map"> + <include file-name="map" location="global"/> + + <conversion-rule> + + <native-to-target> + PyObject* %out = PyDict_New(); + %INTYPE::const_iterator it = %in.begin(); + for (; it != %in.end(); ++it) { + %INTYPE_0 key = it->first; + %INTYPE_1 value = it->second; + PyDict_SetItem(%out, + %CONVERTTOPYTHON[%INTYPE_0](key), + %CONVERTTOPYTHON[%INTYPE_1](value)); + } + return %out; + </native-to-target> + + <target-to-native> + + <add-conversion type="PyDict"> + PyObject* key; + PyObject* value; + Py_ssize_t pos = 0; + while (PyDict_Next(%in, &pos, &key, &value)) { + %OUTTYPE_0 cppKey = %CONVERTTOCPP[%OUTTYPE_0](key); + %OUTTYPE_1 cppValue = %CONVERTTOCPP[%OUTTYPE_1](value); + %out.insert(%OUTTYPE::value_type(cppKey, cppValue)); + } + </add-conversion> + + </target-to-native> + </conversion-rule> + </container-type> + + +.. _variables_and_functions: + +Variables & Functions +===================== + + +.. _in: + +**%in** + + Variable replaced by the C++ input variable. + + +.. _out: + +**%out** + + Variable replaced by the C++ output variable. Needed to convey the + result of a Python to C++ conversion. + + +.. _intype: + +**%INTYPE** + + Used in Python to C++ conversions. It is replaced by the name of type for + which the conversion is being defined. Don't use the type's name directly. + + +.. _intype_n: + +**%INTYPE_#** + + Replaced by the name of the #th type used in a container. + + +.. _outtype: + +**%OUTTYPE** + + Used in Python to C++ conversions. It is replaced by the name of type for + which the conversion is being defined. Don't use the type's name directly. + + +.. _outtype_n: + +**%OUTTYPE_#** + + Replaced by the name of the #th type used in a container. + + +.. _checktype: + +**%CHECKTYPE[CPPTYPE]** + + Replaced by a |project| type checking function for a Python variable. + The C++ type is indicated by ``CPPTYPE``. + + +.. _oldconverters: + +Converting The Old Converters +============================= + +If you use |project| for your bindings, and has defined some type conversions +using the ``Shiboken::Converter`` template, then you must update your converters +to the new scheme. + +Previously your conversion rules were declared in one line, like this: + + + .. code-block:: xml + + <primitive-type name="Complex" target-lang-api-name="PyComplex"> + <include file-name="complex.h" location="global"/> + <conversion-rule file="complex_conversions.h"/> + </primitive-type> + + +And implemented in a separate C++ file, like this: + + + .. code-block:: c++ + + namespace Shiboken { + template<> struct Converter<Complex> + { + static inline bool checkType(PyObject* pyObj) { + return PyComplex_Check(pyObj); + } + static inline bool isConvertible(PyObject* pyObj) { + return PyComplex_Check(pyObj); + } + static inline PyObject* toPython(void* cppobj) { + return toPython(*reinterpret_cast<Complex*>(cppobj)); + } + static inline PyObject* toPython(const Complex& cpx) { + return PyComplex_FromDoubles(cpx.real(), cpx.imag()); + } + static inline Complex toCpp(PyObject* pyobj) { + double real = PyComplex_RealAsDouble(pyobj); + double imag = PyComplex_ImagAsDouble(pyobj); + return Complex(real, imag); + } + }; + } + + +In this case, the parts of the implementation that will be used in the new +conversion-rule are the ones in the two last method +``static inline PyObject* toPython(const Complex& cpx)`` and +``static inline Complex toCpp(PyObject* pyobj)``. The ``isConvertible`` method +is gone, and the ``checkType`` is now an attribute of the :ref:`add-conversion <add-conversion>` +tag. Refer back to the first example in this page and you will be able to +correlate the above template with the new scheme of conversion rule definition. diff --git a/sources/shiboken6/doc/typesystem_documentation.rst b/sources/shiboken6/doc/typesystem_documentation.rst new file mode 100644 index 000000000..d73e43cb1 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_documentation.rst @@ -0,0 +1,43 @@ +Manipulating Documentation +-------------------------- + +inject-documentation +^^^^^^^^^^^^^^^^^^^^ + + The inject-documentation node inserts the documentation into the generated + documentation. This node is a child of the object-type, value-type and + modify-function nodes. + + .. code-block:: xml + + <value-type> + <inject-documentation mode="append | prepend | replace" format="native | target" > + // the documentation + </inject-code> + </value-type> + + The **mode** attribute default value is *replace*. + + The **format** attribute specifies when the documentation injection will + occur and it accepts the following values: + + * native: Before XML<->Backend transformation occur, so the injected code *must* be a valid XML. + * target: After XML<->Backend transformation occur, so the injected code *must* be a valid backend format. + + At the moment the only supported backend is Sphinx. + +modify-documentation +^^^^^^^^^^^^^^^^^^^^ + + The modify-documentation node allows you to change the auto-generated + documentation. API Extractor transforms XML's from qdoc (the Qt documentation + tool) into .rst files to be processed later using Sphinx. You can modify + the XML before the transformation takes place. + + .. code-block:: xml + + <modify-documentation xpath="..."> + <!-- new documentation --> + </modify-documentation> + + The **xpath** attribute is the XPath to the node that you want to modify. diff --git a/sources/shiboken6/doc/typesystem_manipulating_objects.rst b/sources/shiboken6/doc/typesystem_manipulating_objects.rst new file mode 100644 index 000000000..d87b816a3 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_manipulating_objects.rst @@ -0,0 +1,310 @@ +.. _manipulating-object-and-value-types: + +Manipulating Object and Value Types +----------------------------------- + +.. _inject-code: + +inject-code +^^^^^^^^^^^ + The inject-code node inserts the given code into the generated code for the + given type or function, and it is a child of the :ref:`object-type`, :ref:`value-type`, + :ref:`modify-function` and :ref:`add-function` nodes. + + The code can be embedded into XML (be careful to use the correct XML entities + for characters like '<', '>', '&'): + + .. code-block:: xml + + <value-type> + <inject-code class="native | target | target-declaration" + position="beginning | end" since="..."> + // the code + </inject-code> + </value-type> + + or obtained from an external file: + + .. code-block:: xml + + <value-type> + <inject-code class="native | target | target-declaration" + position="beginning | end" since="..." + file="external_source.cpp" + snippet="label"/> + </value-type> + + + The ``class`` attribute specifies which module of the generated code that + will be affected by the code injection + (see :ref:`codegenerationterminology`). The ``class`` attribute accepts the + following values: + + * native: The c++ code + * target: The binding code + * target-declaration: The code will be injected into the generated header + file containing the c++ wrapper class definition. + * file: The file name + * snippet: The snippet label (optional) + + If the ``position`` attribute is set to *beginning* (the default), the code + is inserted at the beginning of the function. If it is set to *end*, the code + is inserted at the end of the function. + + The ``since`` attribute specify the API version where this code was injected. + + If a ``snippet`` label is given, the code between annotations of the form + + .. code-block:: c++ + + // @snippet label + ... + // @snippet label + + will be extracted. + + For a detailed description, see :ref:`codeinjectionsemantics`. + +modify-field +^^^^^^^^^^^^ + + The modify-field node allows you to alter the access privileges for a given + C++ field when mapping it onto the target language, and it is a child of an + :ref:`object-type` or a :ref:`value-type` node. + + .. code-block:: xml + + <object-type> + <modify-field name="..." + write="true | false" + read="true | false" /> + </object-type> + + The ``name`` attribute is the name of the field, the *optional* ``write`` + and ``read`` attributes specify the field's access privileges in the target + language API (both are set to true by default). + The ``remove`` attribute is an *optional* attribute, which can mark the field + to be discarded on generation; it has the same purpose of the deprecated tag + :ref:`remove`. + +.. _modify-function: + +modify-function +^^^^^^^^^^^^^^^ + + The modify-function node allows you to modify a given C++ function when mapping + it onto the target language, and it is a child of an :ref:`object-type` or a :ref:`value-type` + node. Use the :ref:`modify-argument` node to specify which argument the modification + affects. + + .. code-block:: xml + + <object-type> + <modify-function signature="..." + since="..." + remove="all | c++" + access="public | private | protected" + allow-thread="true | auto | false" + exception-handling="off | auto-off | auto-on | on" + overload-number="number" + rename="..." /> + </object-type> + + The ``signature`` attribute is a normalized C++ signature, excluding return + values but including potential const declarations. + + The ``since`` attribute specify the API version when this function was modified. + + The ``allow-thread`` attribute specifies whether a function should be wrapped + into ``Py_BEGIN_ALLOW_THREADS`` and ``Py_END_ALLOW_THREADS``, that is, + temporarily release the GIL (global interpreter lock). Doing so is required + for any thread-related function (wait operations), functions that might call + a virtual function (potentially reimplemented in Python), and recommended for + lengthy I/O operations or similar. It has performance costs, though. + The value ``auto`` means that it will be turned off for functions for which + it is deemed to be safe, for example, simple getters. + The attribute defaults to ``false``. + + The ``exception-handling`` attribute specifies whether to generate exception + handling code (nest the function call into try / catch statements). It accepts + the following values: + + * no, false: Do not generate exception handling code + * auto-off: Generate exception handling code for functions + declaring a non-empty ``throw`` list + * auto-on: Generate exception handling code unless function + declares ``noexcept`` + * yes, true: Always generate exception handling code + + The optional ``overload-number`` attribute specifies the position of the + overload when checking arguments. Typically, when a number of overloads + exists, as for in example in Qt: + + .. code-block:: c++ + + void QPainter::drawLine(QPointF, QPointF); + void QPainter::drawLine(QPoint, QPoint); + + they will be reordered such that the check for matching arguments for the + one taking a ``QPoint`` is done first. This is to avoid a potentially + costly implicit conversion from ``QPoint`` to ``QPointF`` when using the + 2nd overload. There are cases though in which this is not desired; + most prominently when a class inherits from a container and overloads exist + for both types as is the case for the ``QPolygon`` class: + + .. code-block:: c++ + + class QPolygon : public QList<QPoint> {}; + + void QPainter::drawPolygon(QPolygon); + void QPainter::drawPolygon(QList<QPoint>); + + By default, the overload taking a ``QList`` will be checked first, trying + to avoid constructing a ``QPolygon`` from ``QList``. The type check for a + list of points will succeed for a parameter of type ``QPolygon``, too, + since it inherits ``QList``. This presents a problem since the sequence + type check is costly due to it checking that each container element is a + ``QPoint``. It is thus preferable to check for the ``QPolygon`` overload + first. This is achieved by specifying numbers as follows: + + .. code-block:: xml + + <object-type name="QPainter"> + <modify-function signature="drawPolygon(QPolygon)" overload-number="0"/> + <modify-function signature="drawPolygon(QList<QPoint>)" overload-number="1"/> + </object-type> + + Numbers should be given for all overloads; otherwise, the order will be in + declaration order. + + The ``remove``, ``access`` and ``rename`` attributes are *optional* attributes + for added convenience; they serve the same purpose as the deprecated tags :ref:`remove`, :ref:`access` and :ref:`rename`. + +.. _add-function: + +add-function +^^^^^^^^^^^^ + + The add-function node allows you to add a given function onto the target language, + and it is a child of an :ref:`object-type` or :ref:`value-type` nodes if the + function is supposed to be a method, or :ref:`namespace` and :ref:`typesystem` if + the function is supposed to be a function inside a namespace or a global function. + + Typically when adding a function some code must be injected to provide the function + logic. This can be done using the :ref:`inject-code` node. + + .. code-block:: xml + + <object-type> + <add-function signature="..." return-type="..." access="public | protected" static="yes | no" since="..."/> + </object-type> + + The ``return-type`` attribute defaults to *void*, the ``access`` to *public* and the ``static`` one to *no*. + + The ``since`` attribute specify the API version when this function was added. + + Within the signature, names for the function parameters can be specified by + enclosing them within the delimiter *@*: + + .. code-block:: + + void foo(int @parameter1@,float) + +.. _conversion-rule-on-types: + +conversion-rule +^^^^^^^^^^^^^^^ + + The conversion-rule node allows you to write customized code to convert the given argument between the target + language and C++, and is a child of the :ref:`value-type`, :ref:`object-type`, :ref:`primitive-type` and + :ref:`container-type` nodes. + + The code pointed by the file attribute is very tied to the generator using APIExtractor, so it don't follow any + rules, but the generator rules.. + + .. code-block:: xml + + <value-type name="Foo"> + <convertion-rule file="my_converter_implementation.h" since="..."/> + </value-type> + + The ``since`` attribute specify the API version when this conversion rule became valid. + + .. note:: You can also use the conversion-rule node to specify :ref:`how the conversion of a single function argument should be done in a function <conversion-rule>`. + + The ``file`` and ``snippet`` attributes are also supported (see :ref:`inject-code` nodes). + + +property +^^^^^^^^ + + The ``property`` element allows you to specify properties consisting of + a type and getter and setter functions. + + It may appear as a child of a complex type such as ``object-type`` or + ``value-type``. + + If the PySide2 extension is not present, code will be generated using the + ``PyGetSetDef`` struct, similar to what is generated for fields. + + If the PySide2 extension is present, those properties complement the + properties obtained from the ``Q_PROPERTY`` macro in Qt-based code. + The properties will be handled in ``libpyside`` unless code generation + is forced. + + .. code-block:: xml + + <property name="..." type="..." get="..." set="..." " generate-getsetdef="yes | no" since="..."/> + + The ``name`` attribute specifies the name of the property, the ``type`` + attribute specifies the C++ type and the ``get`` attribute specifies the + name of the accessor function. + + The optional ``set`` attribute specifies name of the setter function. + + The optional ``generate-getsetdef`` attribute specifies whether to generate + code for if the PySide2 extension is present (indicating this property is not + handled by libpyside). It defaults to *no*. + + The optional ``since`` attribute specifies the API version when this + property appears. + + For a typical C++ class, like: + + .. code-block:: c++ + + class Test { + public: + int getValue() const; + void setValue(); + }; + + ``value`` can then be specified to be a property: + + .. code-block:: xml + + <value-type name="Test"> + <property name="value" type="int" get="getValue" set="setValue"/> + + With that, a more pythonic style can be used: + + .. code-block:: python + + test = Test() + test.value = 42 + + For Qt classes (with the PySide2 extension present), additional setters + and getters that do not appear as ``Q_PROPERTY``, can be specified to + be properties: + + .. code-block:: xml + + <object-type name="QMainWindow"> + <property name="centralWidget" type="QWidget *" get="centralWidget" set="setCentralWidget"/> + + in addition to the normal properties of ``QMainWindow`` defined for + Qt Designer usage. + + .. note:: In the *Qt* coding style, the property name typically conflicts + with the getter name. It is recommended to exclude the getter from the + wrapper generation using the ``remove`` function modification. diff --git a/sources/shiboken6/doc/typesystem_modify_function.rst b/sources/shiboken6/doc/typesystem_modify_function.rst new file mode 100644 index 000000000..071cea4f5 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_modify_function.rst @@ -0,0 +1,78 @@ +.. _modifying-functions: + +Modifying Functions +------------------- + +.. _modify-argument: + +modify-argument +^^^^^^^^^^^^^^^ + + The modify-argument node specifies which of the given function's arguments the + modification affects, and is a child of the modify-function node. Use the + remove-argument, replace-default-expression, remove-default-expression, + replace-type, reference-count and define-ownership nodes to specify the details + of the modification. + + .. code-block:: xml + + <modify-function> + <modify-argument index="return | this | 1 ..." > + // modifications + </modify-argument> + </modify-function> + + Set the ``index`` attribute to "1" for the first argument, "2" for the second + one and so on. Alternatively, set it to "return" or "this" if you want to + modify the function's return value or the object the function is called upon, + respectively. + +.. _remove: + +remove +^^^^^^ + + The remove node removes the given method from the generated target language + API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <remove class="all" /> + </modify-function> + + .. warning:: This tag is deprecated, use the ``remove`` attribute from :ref:`modify-function` tag instead. + +.. _access: + +access +^^^^^^ + + The access node changes the access privileges of the given function in the + generated target language API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <access modifier="public | protected | private"/> + </modify-function> + + .. warning:: This tag is deprecated, use the ``access`` attribute from :ref:`modify-function` tag instead. + +.. _rename: + +rename +^^^^^^ + + The rename node changes the name of the given function in the generated target + language API, and it is a child of the modify-function node. + + .. code-block:: xml + + <modify-function> + <rename to="..." /> + </modify-function> + + The ``to`` attribute is the new name of the function. + + .. warning:: This tag is deprecated, use the ``rename`` attribute from :ref:`modify-function` tag instead. diff --git a/sources/shiboken6/doc/typesystem_ownership.rst b/sources/shiboken6/doc/typesystem_ownership.rst new file mode 100644 index 000000000..a2ee8e1fa --- /dev/null +++ b/sources/shiboken6/doc/typesystem_ownership.rst @@ -0,0 +1,234 @@ +.. _objectownership: + +**************** +Object ownership +**************** + +One of the main things a binding developer should have in mind is +how the C++ instances lives will cope with Python's reference count. +The last thing you want is to crash a program due to a segfault +when your C++ instance was deleted and the +wrapper object tries to access the invalid memory there. + +In this section we'll show how |project| deals with object ownership +and parentship, taking advantage of the information provided by the +APIExtractor. + +Ownership basics +================ + +As any python binding, |project|-based bindings uses reference counting +to handle the life of the wrapper object (the Python object that contains the +C++ object, do not confuse with the *wrapped* C++ object). +When a reference count reaches zero, the wrapper is deleted by Python garbage +collector and tries to delete the wrapped instance, but sometimes the wrapped +C++ object is already deleted, or maybe the C++ object should not be freed after +the Python wrapper go out of scope and die, because C++ is already taking care of +the wrapped instance. + +In order to handle this, you should tell the +generator whether the instance's ownership belongs to the binding or +to the C++ Library. When belonging to the binding, we are sure that the C++ object +won't be deleted by C++ code and we can call the C++ destructor when the refcount +reaches 0. Otherwise, instances owned by C++ code can be destroyed arbitrarily, +without notifying the Python wrapper of its destruction. + +Invalidating objects +==================== + +To prevent segfaults and double frees, the wrapper objects are invalidated. +An invalidated can't be passed as argument or have an attribute or method accessed. +Trying to do this will raise RuntimeError. + +The following situations can invalidate an object: + +C++ taking ownership +-------------------- + + When an object is passed to a function or method that takes ownership of it, the wrapper + is invalidated as we can't be sure of when the object is destroyed, unless it has a + :ref:`virtual destructor <ownership-virt-method>` or the transfer is due to the special case + of :ref:`parent ownership <ownership-parent>`. + + Besides being passed as argument, the called object can have its ownership changed, like + the `setParent` method in Qt's `QObject`. + +Invalidate after use +-------------------- + + Objects marked with *invalidate-after-use* in the type system description always are + virtual method arguments provided by a C++ originated call. They should be + invalidated right after the Python function returns. + +.. _ownership-virt-method: + +Objects with virtual methods +---------------------------- + + A little bit of implementation details: + virtual methods are supported by creating a C++ class, the **shell**, that inherits + from the class with virtual methods, the native one, and override those methods to check if + any derived class in Python also override it. + + If the class has a virtual destructor (and C++ classes with virtual methods should have), this + C++ instance invalidates the wrapper only when the overridden destructor is called. + + One exception to this rule is when the object is created in C++, like in a + factory method. This way the wrapped object is a C++ instance of the native + class, not the shell one, and we cannot know when it is destroyed. + +.. _ownership-parent: + +Parent-child relationship +========================= + +One special type of ownership is the parent-child relationship. +Being a child of an object means that when the object's parent dies, +the C++ instance also dies, so the Python references will be invalidated. +Qt's QObject system, for example, implements this behavior, but this is valid +for any C++ library with similar behavior. + +.. _ownership-parent-heuristics: + +Parentship heuristics +--------------------- + + As the parent-child relationship is very common, |project| tries to automatically + infer what methods falls into the parent-child scheme, adding the extra + directives related to ownership. + + This heuristic will be triggered when generating code for a method and: + + * The function is a constructor. + * The argument name is `parent`. + * The argument type is a pointer to an object. + + When triggered, the heuristic will set the argument named "parent" + as the parent of the object being created by the constructor. + + The main focus of this process was to remove a lot of hand written code from + type system when binding Qt libraries. For Qt, this heuristic works in all cases, + but be aware that it might not when binding your own libraries. + + To activate this heuristic, use the :ref:`--enable-parent-ctor-heuristic <parent-heuristic>` + command line switch. + +.. _return-value-heuristics: + +Return value heuristics +----------------------- + + When enabled, object returned as pointer in C++ will become child of the object on which the method + was called. + + To activate this heuristic, use the :ref:`--enable-return-value-heuristic <return-heuristic>` + +Common pitfalls +=============== + +Not saving unowned objects references +------------------------------------- + + Sometimes when you pass an instance as argument to a method and the receiving + instance will need that object to live indefinitely, but will not take ownership + of the argument instance. In this case, you should hold a reference to the argument + instance. + + For example, let's say that you have a renderer class that will use a source class + in a setSource method but will not take ownership of it. The following code is wrong, + because when `render` is called the `Source` object created during the call to `setSource` + is already destroyed. + + .. code-block:: python + + renderer.setModel(Source()) + renderer.render() + + To solve this, you should hold a reference to the source object, like in + + .. code-block:: python + + source = Source() + renderer.setSource(source) + renderer.render() + + +Ownership Management in the Typesystem +======================================= + +For the possible values of the ``class`` attribute, see +:ref:`codegenerationterminology`. + +Ownership transfer from C++ to target +------------------------------------- + + When an object currently owned by C++ has its ownership transferred + back to the target language, the binding can know for sure when the object will be deleted and + tie the C++ instance existence to the wrapper, calling the C++ destructor normally when the + wrapper is deleted. + + .. code-block:: xml + + <modify-argument index="1"> + <define-ownership class="target" owner="target" /> + </modify-argument> + +Ownership transfer from target to C++ +------------------------------------- + + In the opposite direction, when an object ownership is transferred from the target language + to C++, the native code takes full control of the object life and you don't + know when that object will be deleted, rendering the wrapper object invalid, + unless you're wrapping an object with a virtual destructor, + so you can override it and be notified of its destruction. + + By default it's safer to just render the wrapper + object invalid and raise some error if the user tries to access + one of this objects members or pass it as argument to some function, to avoid unpleasant segfaults. + Also you should avoid calling the C++ destructor when deleting the wrapper. + + .. code-block:: xml + + <modify-argument index="1"> + <define-ownership class="target" owner="c++" /> + </modify-argument> + + +Parent-child relationship +------------------------- + +One special type of relationship is the parent-child. When an object is called +the parent of another object (the child), the former is in charge of deleting its +child when deleted and the target language can trust that the child will be alive +as long as the parent is, unless some other method can take the C++ ownership away from the parent. + +One of the main uses of this scheme is Qt's object system, with ownership among QObject-derived +classes, creating "trees" of instances. + + .. code-block:: xml + + <modify-argument index="this"> + <parent index="1" action="add"> + </modify-argument> + +In this example, the instance with the method that is being invoked (indicated by 'index="this"' on +modify-argument) will be marked as a child +of the first argument using the `parent` tag. To remove ownership, just use "remove" in the action attribute. **Removing +parentship also transfers the ownership back to python.** + +Invalidation after use +---------------------- + +Sometimes an object is created as a virtual method call argument and destroyed after the +call returned. In this case, you should use the ``invalidate-after-use`` attribute in the +``modify-argument`` tag to mark the wrapper as invalid right after the virtual method returns. + + .. code-block:: xml + + <modify-argument index="2" invalidate-after-use="yes"/> + +In this example the second argument will be invalidated after this method call. + +See `Object Trees and Object Ownership`_. + +.. _`Object Trees and Object Ownership`: http://doc.qt.io/qt-5/objecttrees.html diff --git a/sources/shiboken6/doc/typesystem_sequenceprotocol.rst b/sources/shiboken6/doc/typesystem_sequenceprotocol.rst new file mode 100644 index 000000000..742be3d70 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_sequenceprotocol.rst @@ -0,0 +1,29 @@ +Sequence Protocol +----------------- + +Support for the sequence protocol is achieved adding functions with special +names, this is done using the add-function tag. + +The special function names are: + + ============= =============================================== ==================== =================== + Function name Parameters Return type CPython equivalent + ============= =============================================== ==================== =================== + __len__ PyObject* self Py_ssize_t PySequence_Size + __getitem__ PyObject* self, Py_ssize_t _i PyObject* PySequence_GetItem + __setitem__ PyObject* self, Py_ssize_t _i, PyObject* _value int PySequence_SetItem + __contains__ PyObject* self, PyObject* _value int PySequence_Contains + __concat__ PyObject* self, PyObject* _other PyObject* PySequence_Concat + ============= =============================================== ==================== =================== + +You just need to inform the function name to the add-function tag, without any +parameter or return type information, when you do it, |project| will create a C +function with parameters and return type defined by the table above. + +The function needs to follow the same semantics of the *CPython equivalent* +function, the only way to do it is using the +:ref:`inject-code <codeinjectionsemantics>` tag. + +A concrete example how to add sequence protocol support to a class can be found +on shiboken tests, more precisely in the definition of the Str class in +``tests/samplebinding/typesystem_sample.xml``. diff --git a/sources/shiboken6/doc/typesystem_solving_compilation.rst b/sources/shiboken6/doc/typesystem_solving_compilation.rst new file mode 100644 index 000000000..23ab9012d --- /dev/null +++ b/sources/shiboken6/doc/typesystem_solving_compilation.rst @@ -0,0 +1,70 @@ +Solving compilation problems +---------------------------- + +suppress-warning +^^^^^^^^^^^^^^^^ + + The generator will generate several warnings which may be irrelevant to the + user. The suppress-warning node suppresses the specified warning, and it is + a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <suppress-warning text="..." /> + </typesystem> + + The **text** attribute is the warning text to suppress, and may contain the * + wildcard (use "" to escape regular expression matching if the warning contain + a regular "*"). + +extra-includes +^^^^^^^^^^^^^^ + + The extra-includes node contains declarations of additional include files, + and it can be a child of the interface-type, namespace-type, value-type and + object-type nodes. + + The generator automatically tries to read the global header for each type but + sometimes it is required to include extra files in the generated C++ code to + make sure that the code compiles. These files must be listed using include + nodes within the extra-include node: + + .. code-block:: xml + + <value-type> + <extra-includes> + <include file-name="..." location="global | local"/> + </extra-includes> + </value-type> + + The **file-name** attribute is the file to include, such as "QStringList". + The **location** attribute is where the file is located: *global* means that + the file is located in $INCLUDEPATH and will be included using #include <...>, + *local* means that the file is in a local directory and will be included + using #include "...". + + +include +^^^^^^^ + + The include node specifies the name and location of a file that must be + included, and it is a child of the interface-type, namespace-type, value-type, + object-type or extra-includes nodes + + The generator automatically tries to read the global header for each type. Use + the include node to override this behavior, providing an alternative file. The + include node can also be used to specify extra include files. + + .. code-block:: xml + + <value-type> + <include file-name="..." + location="global | local"/> + </value-type> + + The **file-name** attribute is the file to include, such as "QStringList". + The **location** attribute is where the file is located: *global* means that + the file is located in $INCLUDEPATH and will be included using #include <...>, + *local* means that the file is in a local directory and will be included + using #include "...". diff --git a/sources/shiboken6/doc/typesystem_specifying_types.rst b/sources/shiboken6/doc/typesystem_specifying_types.rst new file mode 100644 index 000000000..405469ea2 --- /dev/null +++ b/sources/shiboken6/doc/typesystem_specifying_types.rst @@ -0,0 +1,509 @@ +Specifying Types +---------------- + +.. _typesystem: + +Including Snippets +^^^^^^^^^^^^^^^^^^ + +There might be repetitive XML code, for example function modifications that +need to be done on classes that are not related by type inheritance. +It is possible to split out such snippets and include them via an entity reference. + +.. code-block:: xml + + <typesystem> + <object-type name="A"> + &common_function_modifications; + </object-type> + <object-type name="B"> + &common_function_modifications; + </object-type> + </typesystem> + +The entity name is interpreted as file name (with suffix **xml**) appended and resolved +in the type system paths passed as command line argument. + +Note that this is not a standard externally parsed entity due to the limitations +of the underlying parser. + +typesystem +^^^^^^^^^^ + + This is the root node containing all the type system information. It can + have a number of attributes, described below. + + .. code-block:: xml + + <typesystem package="..." default-superclass="..." allow-thread="..." exception-handling="..."> + </typesystem> + + The **package** attribute is a string describing the package to be used, + e.g. "QtCore". + The *optional* **default-superclass** attribute is the canonical C++ base class + name of all objects, e.g., "object". + + The *optional* attributes **allow-thread** and **exception-handling** + specify the default handling for the corresponding function modification + (see :ref:`modify-function`). + +load-typesystem +^^^^^^^^^^^^^^^ + + The load-typesystem node specifies which type systems to load when mapping + multiple libraries to another language or basing one library on another, and + it is a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <load-typesystem name="..." generate="yes | no" /> + </typesystem> + + The **name** attribute is the filename of the typesystem to load, the + **generate** attribute specifies whether code should be generated or not. The + later must be specified when basing one library on another, making the generator + able to understand inheritance hierarchies, primitive mapping, parameter types + in functions, etc. + + Most libraries will be based on both the QtCore and QtGui modules, in which + case code generation for these libraries will be disabled. + + +rejection +^^^^^^^^^ + + The rejection node rejects the given class, or the specified function or + field, and it is a child of the typesystem node. + + .. code-block:: xml + + <typesystem> + <rejection class="..." + function-name="..." + field-name="..." /> + </typesystem> + + The **class** attribute is the C++ class name of the class to reject. Use the + *optional* **function-name** or **field-name** attributes to reject a particular + function or field. Note that the **field-name** and **function-name** cannot + be specified at the same time. To remove all occurrences of a given field or + function, set the class attribute to \*. + +.. _primitive-type: + +primitive-type +^^^^^^^^^^^^^^ + + The primitive-type node describes how a primitive type is mapped from C++ to + the target language, and is a child of the typesystem node. Note that most + primitives are already specified in the QtCore typesystem. + + .. code-block:: xml + + <typesystem> + <primitive-type name="..." + since="..." + until="..." + target-name="..." + default-constructor="..." + preferred-conversion="yes | no" /> + view-on="..." + </typesystem> + + The **name** attribute is the name of the primitive in C++, the optional, + **target-name** attribute is the name of the primitive type in the target + language. If the later two attributes are not specified their default value + will be the same as the **name** attribute. + + The *optional* **since** value is used to specify the API version in which + the type was introduced. + + Similarly, the *optional* **until** value can be used to specify the API + version in which the type will be obsoleted. + + If the *optional* **preferred-conversion** attribute is set to *no*, it + indicates that this version of the primitive type is not the preferred C++ + equivalent of the target language type. For example, in Python both "qint64" + and "long long" become "long" but we should prefer the "qint64" version. For + this reason we mark "long long" with preferred-conversion="no". + + The *optional* **default-constructor** specifies the minimal constructor + call to build one value of the primitive-type. This is not needed when the + primitive-type may be built with a default constructor (the one without + arguments). + + The *optional* **preferred-conversion** attribute tells how to build a default + instance of the primitive type. It should be a constructor call capable of + creating a instance of the primitive type. Example: a class "Foo" could have + a **preferred-conversion** value set to "Foo()". Usually this attribute is + used only for classes declared as primitive types and not for primitive C++ + types, but that depends on the application using *ApiExtractor*. + + The *optional* **view-on** attribute specifies that the type is a view + class like std::string_view or QStringView which has a constructor + accepting another type like std::string or QString. Since typically + no values can be assigned to view classes, no target-to-native conversion + can be generated for them. Instead, an instance of the viewed class should + be instantiated and passed to functions using the view class + for argument types. + +.. _namespace: + +namespace-type +^^^^^^^^^^^^^^ + + The namespace-type node maps the given C++ namespace to the target language, + and it is a child of the typesystem node. Note that within namespaces, the + generator only supports enums (i.e., no functions or classes). + + .. code-block:: xml + + <typesystem> + <namespace-type name="..." + visible="true | auto | false" + generate="yes | no" + generate-using="yes | no" + package="..." + since="..." + revision="..." /> + </typesystem> + + The **name** attribute is the name of the namespace, e.g., "Qt". + + The *optional* **visible** attribute is used specify whether the + namespace is visible in the target language name. Its default value is + **auto**. It means that normal namespaces are visible, but inline namespaces + (as introduced in C++ 11) will not be visible. + + The detection of inline namespaces requires shiboken to be built + using LLVM 9.0. + + The *optional* **generate** is a legacy attribute. Specifying + **no** is equivalent to **visible="false"**. + + The *optional* **generate-using** attribute specifies whether + ``using namespace`` is generated into the wrapper code for classes within + the namespace (default: **yes**). This ensures for example that not fully + qualified enumeration values of default argument values compile. + However, in rare cases, it might cause ambiguities and can then be turned + off. + + The **package** attribute can be used to override the package of the type system. + + The *optional* **since** value is used to specify the API version of this type. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + +enum-type +^^^^^^^^^ + + The enum-type node maps the given enum from C++ to the target language, + and it is a child of the typesystem node. Use the reject-enum-value to + reject values. + + .. code-block:: xml + + <typesystem> + <enum-type name="..." + identified-by-value="..." + class="yes | no" + since="..." + flags="yes | no" + flags-revision="..." + lower-bound="..." + upper-bound="..." + force-integer="yes | no" + extensible="yes | no" + revision="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ name of the enum + (e.g.,"Qt::FillRule"). If the *optional* **flags** attribute is set to *yes* + (the default is *no*), the generator will expect an existing QFlags<T> for the + given enum type. The **lower-bound** and **upper-bound** attributes are used + to specify runtime bounds checking for the enum value. The value must be a + compilable target language statement, such as "QGradient.Spread.PadSpread" + (taking again Python as an example). If the **force-integer** attribute is + set to *yes* (the default is *no*), the generated target language code will + use the target language integers instead of enums. And finally, the + **extensible** attribute specifies whether the given enum can be extended + with user values (the default is *no*). + + The *optional* **since** value is used to specify the API version of this type. + + The attribute **identified-by-value** helps to specify anonymous enums using the + name of one of their values, which is unique for the anonymous enum scope. + Notice that the **enum-type** tag can either have **name** or **identified-by-value** + but not both. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + + The **flags-revision** attribute has the same purposes of **revision** attribute but + is used for the QFlag related to this enum. + + +reject-enum-value +^^^^^^^^^^^^^^^^^ + + The reject-enum-value node rejects the enum value specified by the **name** + attribute, and it is a child of the enum-type node. + + .. code-block:: xml + + <enum-type> + <reject-enum-value name="..."/> + </enum-type> + + This node is used when a C++ enum implementation has several identical numeric + values, some of which are typically obsolete. + +.. _value-type: + +value-type +^^^^^^^^^^ + + The value-type node indicates that the given C++ type is mapped onto the target + language as a value type. This means that it is an object passed by value on C++, + i.e. it is stored in the function call stack. It is a child of the :ref:`typesystem` node. + + .. code-block:: xml + + <typesystem> + <value-type name="..." since="..." + copyable="yes | no" + allow-thread="..." + disable-wrapper="yes | no" + exception-handling="..." + hash-function="..." + stream="yes | no" + default-constructor="..." + revision="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name, such as + "QMatrix" or "QPainterPath::Element". The **copyable** attribute is used to + force or not specify if this type is copyable. The *optional* **hash-function** + attribute informs the function name of a hash function for the type. + + The *optional* attribute **stream** specifies whether this type will be able to + use externally defined operators, like QDataStream << and >>. If equals to **yes**, + these operators will be called as normal methods within the current class. + + The *optional* **since** value is used to specify the API version of this type. + + The *optional* **default-constructor** specifies the minimal constructor + call to build one instance of the value-type. This is not needed when the + value-type may be built with a default constructor (the one without arguments). + Usually a code generator may guess a minimal constructor for a value-type based + on its constructor signatures, thus **default-constructor** is used only in + very odd cases. + + For the *optional* **disable-wrapper** attribute, see :ref:`object-type`. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + + The *optional* attributes **allow-thread** and **exception-handling** + specify the default handling for the corresponding function modification + (see :ref:`modify-function`). + +.. _object-type: + +object-type +^^^^^^^^^^^ + + The object-type node indicates that the given C++ type is mapped onto the target + language as an object type. This means that it is an object passed by pointer on + C++ and it is stored on the heap. It is a child of the :ref:`typesystem` node. + + .. code-block:: xml + + <typesystem> + <object-type name="..." + since="..." + copyable="yes | no" + allow-thread="..." + disable-wrapper="yes | no" + exception-handling="..." + hash-function="..." + stream="yes | no" + revision="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. If there is no + C++ base class, the default-superclass attribute can be used to specify a + superclass for the given type, in the generated target language API. The + **copyable** and **hash-function** attributes are the same as described for + :ref:`value-type`. + + The *optional* **disable-wrapper** attribute disables the generation of a + **C++ Wrapper** (see :ref:`codegenerationterminology`). This will + effectively disable overriding virtuals methods in Python for the class. + It can be used when the class cannot be instantiated from Python and + its virtual methods pose some problem for the code generator (by returning + references, or using a default value that cannot be generated for a + parameter, or similar). + + The *optional* attribute **stream** specifies whether this type will be able to + use externally defined operators, like QDataStream << and >>. If equals to **yes**, + these operators will be called as normal methods within the current class. + + The *optional* **since** value is used to specify the API version of this type. + + The **revision** attribute can be used to specify a revision for each type, easing the + production of ABI compatible bindings. + + The *optional* attributes **allow-thread** and **exception-handling** + specify the default handling for the corresponding function modification + (see :ref:`modify-function`). + +interface-type +^^^^^^^^^^^^^^ + + This type is deprecated and no longer has any effect. Use object-type instead. + +.. _container-type: + +container-type +^^^^^^^^^^^^^^ + + The container-type node indicates that the given class is a container and + must be handled using one of the conversion helpers provided by attribute **type**. + + .. code-block:: xml + + <typesystem> + <container-type name="..." + since="..." + type ="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. The **type** + attribute is used to indicate what conversion rule will be applied to the + container. It can be: *list*, *string-list*, *linked-list*, *vector*, *stack*, + *queue*, *set*, *map*, *multi-map*, *hash*, *multi-hash* or *pair*. + + The *optional* **since** value is used to specify the API version of this container. + +typedef-type +^^^^^^^^^^^^ + + The typedef-type allows for specifying typedefs in the typesystem. They + are mostly equivalent to spelling out the typedef in the included header, which + is often complicated when trying to wrap libraries whose source code cannot be + easily extended. + + .. code-block:: xml + + <typesystem> + <typedef-type name="..." + source="..." + since="..." /> + </typesystem> + + The **source** attribute is the source. Example: + + .. code-block:: xml + + <namespace-type name='std'> + <value-type name='optional' generate='no'/>\n" + </namespace-type> + <typedef-type name="IntOptional" source="std::optional<int>"/> + + is equivalent to + + .. code-block:: c++ + + typedef std::optional<int> IntOptional; + + The *optional* **since** value is used to specify the API version of this type. + +.. _custom-type: + +custom-type +^^^^^^^^^^^ + + The custom-type node simply makes the parser aware of the existence of a target + language type, thus avoiding errors when trying to find a type used in function + signatures and other places. The proper handling of the custom type is meant to + be done by a generator using the APIExractor. + + .. code-block:: xml + + <typesystem> + <custom-type name="..." /> + </typesystem> + + The **name** attribute is the name of the custom type, e.g., "PyObject". + +.. _smart-pointer-type: + +smart-pointer-type +^^^^^^^^^^^^^^^^^^ + + The smart pointer type node indicates that the given class is a smart pointer + and requires inserting calls to **getter** to access the pointeee. + Currently, only the **type** *shared* is supported and the usage is limited + to function return values. + **ref-count-method** specifies the name of the method used to do reference counting. + + The *optional* attribute **instantiations** specifies for which instantiations + of the smart pointer wrappers will be generated (comma-separated list). + By default, this will happen for all instantiations found by code parsing. + This might be a problem when linking different modules, since wrappers for the + same instantiation might be generated into different modules, which then clash. + Providing an instantiations list makes it possible to specify which wrappers + will be generated into specific modules. + + .. code-block:: xml + + <typesystem> + <smart-pointer-type name="..." + since="..." + type="..." + getter="..." + ref-count-method="..." + instantiations="..."/> + </typesystem> + +.. _function: + +function +^^^^^^^^ + + The function node indicates that the given C++ global function is mapped onto + the target language. + + .. code-block:: xml + + <typesystem> + <function signature="..." rename="..." since="..."/> + </typesystem> + + This tag has some limitations, it doesn't support function modifications, besides you + can't add a function overload using :ref:`add-function` tag to an existent function. + These limitation will be addressed in future versions of ApiExtractor. + + The function tag has two *optional* attributes: **since**, whose value is used to specify + the API version of this function, and **rename**, to modify the function name. + +.. _system_include: + +system-include +^^^^^^^^^^^^^^ + + The optional **system-include** specifies the name of a system include + file or a system include path (indicated by a trailing slash) to be + parsed. Normally, include files considered to be system include + files are skipped by the C++ code parser. Its primary use case + is exposing classes from the STL library. + + .. code-block:: xml + + <typesystem> + <system-include file-name="memory"/> + <system-include file-name="/usr/include/Qt/"/> + </typesystem> diff --git a/sources/shiboken6/doc/typesystem_templates.rst b/sources/shiboken6/doc/typesystem_templates.rst new file mode 100644 index 000000000..31b155c5a --- /dev/null +++ b/sources/shiboken6/doc/typesystem_templates.rst @@ -0,0 +1,55 @@ +.. _using-code-templates: + +Using Code Templates +-------------------- + +template +^^^^^^^^ + + The template node registers a template that can be used to avoid duplicate + code when extending the generated code, and it is a child of the typesystem + node. + + .. code-block:: xml + + <typesystem> + <template name="my_template"> + // the code + </template> + </typesystem> + + Use the insert-template node to insert the template code (identified by the + template's ``name`` attribute) into the generated code base. + + +insert-template +^^^^^^^^^^^^^^^ + + The insert-template node includes the code template identified by the name + attribute, and it can be a child of the inject-code, conversion-rule, template, + custom-constructor and custom-destructor nodes. + + .. code-block:: xml + + <inject-code class="target" position="beginning"> + <insert-template name="my_template" /> + </inject-code> + + Use the replace node to modify the template code. + + +replace +^^^^^^^ + + The replace node allows you to modify template code before inserting it into + the generated code, and it can be a child of the insert-template node. + + .. code-block:: xml + + <insert-template name="my_template"> + <replace from="..." to="..." /> + </insert-template> + + This node will replace the attribute ``from`` with the value pointed by + ``to``. + diff --git a/sources/shiboken6/doc/typesystem_variables.rst b/sources/shiboken6/doc/typesystem_variables.rst new file mode 100644 index 000000000..73d4dd12c --- /dev/null +++ b/sources/shiboken6/doc/typesystem_variables.rst @@ -0,0 +1,359 @@ +********************* +Type System Variables +********************* + +User written code can be placed in arbitrary places using the +:ref:`inject-code <inject-code>` tag. To ease the binding developer +work, the injected code can make use of special variables that will be replaced +by the correct values. This also shields the developer from some |project| +implementation specifics. + + +.. _variables: + +Variables +========= + + +.. _cpp_return_argument: + +**%0** + + Replaced by the C++ return variable of the Python method/function wrapper. + + +.. _arg_number: + +**%#** + + Replaced by the name of a C++ argument in the position indicated by ``#``. + The argument counting starts with ``%1``, since ``%0`` represents the return + variable name. If the number indicates a variable that was removed in the + type system description, but there is a default value for it, this value will + be used. Consider this example: + + .. code-block:: c++ + + void argRemoval(int a0, int a1 = 123); + + + .. code-block:: xml + + <modify-function signature="argRemoval(int, int)"> + <modify-argument index="2"> + <remove-argument/> + </modify-argument> + </modify-function> + + The ``%1`` will be replaced by the C++ argument name, and ``%2`` will get the + value ``123``. + + +.. _argument_names: + +**%ARGUMENT_NAMES** + + Replaced by a comma separated list with the names of all C++ arguments that + were not removed on the type system description for the method/function. When + the removed argument has a default value (original or provided in the type + system), this value will be inserted in the argument list. If you want to remove + the argument so completely that it doesn't appear in any form on the + ``%ARGUMENT_NAMES`` replacement, don't forget to remove also its default value + with the :ref:`remove-default-expression <remove-default-expression>` type system tag. + + + Take the following method and related type system description as an example: + + .. code-block:: c++ + + void argRemoval(int a0, Point a1 = Point(1, 2), bool a2 = true, Point a3 = Point(3, 4), int a4 = 56); + + + .. code-block:: xml + + <modify-function signature="argRemoval(int, Point, bool, Point, int)"> + <modify-argument index="2"> + <remove-argument/> + <replace-default-expression with="Point(6, 9)"/> + </modify-argument> + <modify-argument index="4"> + <remove-argument/> + </modify-argument> + </modify-function> + + As seen on the XML description, the function's ``a1`` and ``a3`` arguments + were removed. If any ``inject-code`` for this function uses ``%ARGUMENT_NAMES`` + the resulting list will be the equivalent of using individual argument type + system variables this way: + + .. code-block:: c++ + + %1, Point(6, 9), %3, Point(3, 4), %5 + + +.. _arg_type: + +**%ARG#_TYPE** + + Replaced by the type of a C++ argument in the position indicated by ``#``. + The argument counting starts with ``%1``, since ``%0`` represents the return + variable in other contexts, but ``%ARG0_TYPE`` will not translate to the + return type, as this is already done by the + :ref:`%RETURN_TYPE <return_type>` variable. + Example: + + .. code-block:: c++ + + void argRemoval(int a0, int a1 = 123); + + + .. code-block:: xml + + <modify-function signature="argRemoval(int, int)"> + <modify-argument index="2"> + <remove-argument/> + </modify-argument> + </modify-function> + + The ``%1`` will be replaced by the C++ argument name, and ``%2`` will get the + value ``123``. + + +.. _converttocpp: + +**%CONVERTTOCPP[CPPTYPE]** + + Replaced by a |project| conversion call that converts a Python variable + to a C++ variable of the type indicated by ``CPPTYPE``. + + Typically, this is a variable assignment: + + .. code-block:: c++ + + double value = %CONVERTTOCPP[double](pyValue); + + Pointer assignments are also possible: + + .. code-block:: c++ + + void f(double *valuePtr) + { + *valuePtr = %CONVERTTOCPP[double](pyValue); + + Note however, that for variable definitions, the type must + be a space-delimited token: + + .. code-block:: c++ + + double * valuePtr = %CONVERTTOCPP[double](pyValue); + + since it otherwise would be indistinguishable from the pointer assignment + above. + + It is possible to use "auto" as type. + +.. _converttopython: + +**%CONVERTTOPYTHON[CPPTYPE]** + + Replaced by a |project| conversion call that converts a C++ variable of the + type indicated by ``CPPTYPE`` to the proper Python object. + + +.. _isconvertible: + +**%ISCONVERTIBLE[CPPTYPE]** + + Replaced by a |project| "isConvertible" call that checks if a Python + variable is convertible (via an implicit conversion or cast operator call) + to a C++ variable of the type indicated by ``CPPTYPE``. + + +.. _checktype: + +**%CHECKTYPE[CPPTYPE]** + + Replaced by a |project| "checkType" call that verifies if a Python + if of the type indicated by ``CPPTYPE``. + + +.. _cppself: + +**%CPPSELF** + + Replaced by the wrapped C++ object instance that owns the method in which the + code with this variable was inserted. + +.. _cpptype: + +**%CPPTYPE** + + Replaced by the original name of the C++ class, without any namespace prefix, + that owns the method in which the code with this variable was inserted. It will + work on class level code injections also. Notice that ``CPPTYPE`` differs from + the :ref:`%TYPE <type>` variable, for this latter may be translated to the original + C++ class name or to the C++ wrapper class name. + + Namespaces will are treated as classes, so ``CPPTYPE`` will work for them and their + enclosed functions as well. + +.. _function_name: + +**%FUNCTION_NAME** + + Replaced by the name of a function or method. + + + +.. _py_return_argument: + +**%PYARG_0** + + Replaced by the name of the Python return variable of the Python method/function wrapper. + + +.. _pyarg: + +**%PYARG_#** + + Similar to ``%#``, but is replaced by the Python arguments (PyObjects) + received by the Python wrapper method. + + If used in the context of a native code injection, i.e. in a virtual method + override, ``%PYARG_#`` will be translated to one item of the Python tuple + holding the arguments that should be passed to the Python override for this + virtual method. + + The example + + .. code-block:: c++ + + long a = PyInt_AS_LONG(%PYARG_1); + + + is equivalent of + + .. code-block:: c++ + + long a = PyInt_AS_LONG(PyTuple_GET_ITEM(%PYTHON_ARGUMENTS, 0)); + + + The generator tries to be smart with attributions, but it will work for the + only simplest cases. + + This example + + .. code-block:: c++ + + Py_DECREF(%PYARG_1); + %PYARG_1 = PyInt_FromLong(10); + + + is equivalent of + + .. code-block:: c++ + + Py_DECREF(PyTuple_GET_ITEM(%PYTHON_ARGUMENTS, 0)); + PyTuple_SET_ITEM(%PYTHON_ARGUMENTS, 0, PyInt_FromLong(10)); + + +.. _pyself: + +**%PYSELF** + + Replaced by the Python wrapper variable (a PyObject) representing the instance + bounded to the Python wrapper method which receives the custom code. + + +.. _python_arguments: + +**%PYTHON_ARGUMENTS** + + Replaced by the pointer to the Python tuple with Python objects converted from + the C++ arguments received on the binding override of a virtual method. + This tuple is the same passed as arguments to the Python method overriding the + C++ parent's one. + + +.. _python_method_override: + +**%PYTHON_METHOD_OVERRIDE** + + This variable is used only on :ref:`native method code injections + <codeinjecting_method_native>`, i.e. on the binding overrides for C++ virtual + methods. It is replaced by a pointer to the Python method override. + + +.. _pythontypeobject: + +**%PYTHONTYPEOBJECT** + + Replaced by the Python type object for the context in which it is inserted: + method or class modification. + + +.. _beginallowthreads: + +**%BEGIN_ALLOW_THREADS** + + Replaced by a thread state saving procedure. + Must match with a :ref:`%END_ALLOW_THREADS <endallowthreads>` variable. + + +.. _endallowthreads: + +**%END_ALLOW_THREADS** + + Replaced by a thread state restoring procedure. + Must match with a :ref:`%BEGIN_ALLOW_THREADS <beginallowthreads>` variable. + + +.. _return_type: + +**%RETURN_TYPE** + + Replaced by the type returned by a function or method. + + +.. _type: + +**%TYPE** + + Replaced by the name of the class to which a function belongs. May be used + in code injected at method or class level. + + +.. _example: + +Example +======= + +Just to illustrate the usage of the variables described in the previous +sections, below is an excerpt from the type system description of a |project| +test. It changes a method that received ``argc/argv`` arguments into something +that expects a Python sequence instead. + + .. code-block:: xml + + <modify-function signature="overloadedMethod(int, char**)"> + <modify-argument index="1"> + <replace-type modified-type="PySequence" /> + </modify-argument> + <modify-argument index="2"> + <remove-argument /> + </modify-argument> + <inject-code class="target" position="beginning"> + int argc; + char** argv; + if (!PySequence_to_argc_argv(%PYARG_1, &argc, &argv)) { + PyErr_SetString(PyExc_TypeError, "error"); + return 0; + } + %RETURN_TYPE foo = %CPPSELF.%FUNCTION_NAME(argc, argv); + %0 = %CONVERTTOPYTHON[%RETURN_TYPE](foo); + + for (int i = 0; i < argc; ++i) + delete[] argv[i]; + delete[] argv; + </inject-code> + </modify-function> |
