diff options
Diffstat (limited to 'sources/shiboken2/doc')
34 files changed, 2840 insertions, 464 deletions
diff --git a/sources/shiboken2/doc/CMakeLists.txt b/sources/shiboken2/doc/CMakeLists.txt index 5903e9dfc..ae4858f95 100644 --- a/sources/shiboken2/doc/CMakeLists.txt +++ b/sources/shiboken2/doc/CMakeLists.txt @@ -1,11 +1,50 @@ +cmake_minimum_required(VERSION 3.1) + +if(FULLDOCSBUILD EQUAL 0) + project(shiboken2_doc) +endif() find_program(SPHINX sphinx-build DOC "Path to sphinx-build binary.") if (SPHINX) - message("-- sphinx-build - found") + message(STATUS "sphinx-build - found") configure_file(conf.py.in conf.py @ONLY) - add_custom_target(doc ${SPHINX} -b html -c . ${CMAKE_CURRENT_SOURCE_DIR} html ) + # 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),'shiboken2',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("-- sphinx-build - not found! doc target disabled") + 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...) diff --git a/sources/shiboken2/doc/_templates/layout.html b/sources/shiboken2/doc/_templates/layout.html index 94ff3534e..2e2e9e892 100644 --- a/sources/shiboken2/doc/_templates/layout.html +++ b/sources/shiboken2/doc/_templates/layout.html @@ -8,7 +8,7 @@ <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) }}" width="199" height="102" /></a></div> + <div class="logo"><a href="http://www.pyside.org"><img alt="PySide" src="{{ pathto('_static/pysidelogo.png', 1) }}"/></a></div> {{ relbar() }} </div> </div> diff --git a/sources/shiboken2/doc/_themes/pysidedocs/static/pyside.css b/sources/shiboken2/doc/_themes/pysidedocs/static/pyside.css index 23e460262..f6a1c5ae4 100644 --- a/sources/shiboken2/doc/_themes/pysidedocs/static/pyside.css +++ b/sources/shiboken2/doc/_themes/pysidedocs/static/pyside.css @@ -552,6 +552,9 @@ tt.descname { .container { padding:0 2% } + .sphinxsidebar { + top: 16px !important; + } } #navbar .navbar-oneQt { display:inline; @@ -930,6 +933,7 @@ html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abb 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 @@ -1020,7 +1024,8 @@ body { color:#404244; } ol,ul { - list-style:none + list-style-type: square; + color: #17a81a; } .body ol,.body ul { margin-top:0.75em; @@ -1170,7 +1175,9 @@ div.multi-column div { .col-2 h2,.toc h3,.sidebar-content h2, .sidebar-content h3,.sectionlist h2, .sphinxsidebar { - position: fixed; + position: -webkit-sticky; + position: sticky; + top: 64px; overflow: scroll; overflow-x: hidden; overflow-y: hidden; @@ -1463,7 +1470,7 @@ div.pre { height:auto } pre, .LegaleseLeft { - background-color:#3a4055; + background-color:#222840; color:#fff; display:block; font-family:"Droid Sans Mono"; @@ -1544,6 +1551,11 @@ pre span.wrap { margin:4px; opacity:0.65 } + +span.pre { + color: #09102d; +} + span.wrap:hover { opacity:1 } @@ -2013,3 +2025,52 @@ a.plink, a.headerlink { 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/shiboken2/doc/_themes/pysidedocs_qthelp/domainindex.html b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/domainindex.html new file mode 100644 index 000000000..c136cdd1c --- /dev/null +++ b/sources/shiboken2/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/shiboken2/doc/_themes/pysidedocs_qthelp/static/fakebar.png b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/fakebar.png Binary files differnew file mode 100644 index 000000000..b45830e00 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/fakebar.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/logo_python.jpg b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/logo_python.jpg Binary files differnew file mode 100644 index 000000000..cd474efba --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/logo_python.jpg diff --git a/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/logo_qt.png b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/logo_qt.png Binary files differnew file mode 100644 index 000000000..3bc03b7c7 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/logo_qt.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/minus.png b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/minus.png Binary files differnew file mode 100644 index 000000000..da1c5620d --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/minus.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/plus.png b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/plus.png Binary files differnew file mode 100644 index 000000000..b3cb37425 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/plus.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/pyside.css b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/pyside.css new file mode 100644 index 000000000..aee5e4420 --- /dev/null +++ b/sources/shiboken2/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/shiboken2/doc/_themes/pysidedocs_qthelp/static/pysidelogo.png b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/pysidelogo.png Binary files differnew file mode 100644 index 000000000..3a2f2bd17 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/pysidelogo.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/relbar_bg.png b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/relbar_bg.png Binary files differnew file mode 100644 index 000000000..4036733a7 --- /dev/null +++ b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/static/relbar_bg.png diff --git a/sources/shiboken2/doc/_themes/pysidedocs_qthelp/theme.conf b/sources/shiboken2/doc/_themes/pysidedocs_qthelp/theme.conf new file mode 100644 index 000000000..4384b459c --- /dev/null +++ b/sources/shiboken2/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/shiboken2/doc/conf.py.in b/sources/shiboken2/doc/conf.py.in index e158abbbe..f99af0fff 100644 --- a/sources/shiboken2/doc/conf.py.in +++ b/sources/shiboken2/doc/conf.py.in @@ -25,7 +25,12 @@ import sys, os 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 """ @@ -158,3 +163,6 @@ html_show_sourcelink = False # 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/shiboken2/doc/wordsofadvice.rst b/sources/shiboken2/doc/considerations.rst index 9aebf1f03..3488c3407 100644 --- a/sources/shiboken2/doc/wordsofadvice.rst +++ b/sources/shiboken2/doc/considerations.rst @@ -110,3 +110,74 @@ this you will need use the new style class: 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/shiboken2/doc/examples/index.rst b/sources/shiboken2/doc/examples/index.rst new file mode 100644 index 000000000..92a64195e --- /dev/null +++ b/sources/shiboken2/doc/examples/index.rst @@ -0,0 +1,9 @@ +Examples +======== + +C++ examples +------------ + +.. toctree:: + + samplebinding.rst diff --git a/sources/shiboken2/doc/samplebinding.rst b/sources/shiboken2/doc/examples/samplebinding.rst index be8dd3ae5..a53b32bac 100644 --- a/sources/shiboken2/doc/samplebinding.rst +++ b/sources/shiboken2/doc/examples/samplebinding.rst @@ -1,9 +1,9 @@ SampleBinding Example *********************** -The example showcases how you can generate CPython-based binding code for a -C++ library using Shiboken. The C++ library is called :code:`Universe`, -with two classes: :code:`Icecream` and :code:`Truck`. Ice creams are +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. @@ -52,7 +52,7 @@ First, let's look at the definition of the two classes: std::vector m_flavors; }; -Here is a summary of what the :code:`Universe` library includes: +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 @@ -63,14 +63,14 @@ Here is a summary of what the :code:`Universe` library includes: 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 +* The :code:`Truck::deliver()` method tells us if the ice-cream delivery was successful. Shiboken typesystem ==================== -Now that the library definitions are in place, Shiboken generator needs a header -file that includes the types we are interested in: +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 @@ -107,10 +107,10 @@ relationship between C++ and Python types: </value-type> </typesystem> -The first important thing to notice here is that we declare :code:`"bool"` and +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. -It can then generate relevant conversion code between C++ and Python, although +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 @@ -126,12 +126,12 @@ you want to modify them. Object ownership rules ======================= -Shiboken cannot magically know who is responsible for freeing the C++ objects -allocated in the Python code. It can guess, but it’s not always correct. There -can be cases where Python should release the C++ memory when the ref count -of the Python object becomes zero. It should never delete the C++ object assuming -that it will not be deleted by the C++ library or maybe it’s parented to another -object (like QWidgets). +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. @@ -142,27 +142,26 @@ 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. -Building -========= +Build +===== To build the :code:`Universe` custom library and then generate bindings for it, -use the :file:`CMakeLists.txt` file provided with the example. You can reuse the -file for your own libraries with minor changes. +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 :command:`"cmake ."` from the prompt to configure the -project and build with the toolchain of your choice (we recommend the -‘(N)Makefiles’ generator though). +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 that can be -imported in your Python script. +the custom C++ library, and the latter is the Python module to import in your +Python script. -Refer to the :file:`README.md` file for more details about the Windows-specific -build instructions. +For more details about these platforms, see the :file:`README.md` file. -Using the Python module -======================== +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: @@ -234,17 +233,14 @@ types from :code:`Icecream` for different “flavors”. It then creates a 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. -The script above shows how to derive from C++ types, override virtual methods, -create and destroy objects, and more. Try running it to see if the ice creams -are delivered. +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:`Shiboken module <shibokenmodule>` - * :doc:`Type System Variables <typesystemvariables>` - * :doc:`User Defined Type Conversion <typeconverters>` - * :doc:`Object ownership <ownership>` - * :doc:`Frequently Asked Questions <faq>` + * :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/shiboken2/doc/faq.rst b/sources/shiboken2/doc/faq.rst deleted file mode 100644 index eb77e5822..000000000 --- a/sources/shiboken2/doc/faq.rst +++ /dev/null @@ -1,71 +0,0 @@ -************************** -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/shiboken2/doc/gettingstarted.rst b/sources/shiboken2/doc/gettingstarted.rst new file mode 100644 index 000000000..321db9545 --- /dev/null +++ b/sources/shiboken2/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 Shiboken2 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 shiboken2 python module) + python setup.py install --qmake=/path/to/qmake \ + --build-tests \ + --verbose-build \ + --internal-build-type=shiboken2 + + # For the executable + python setup.py install --qmake=/path/to/qmake \ + --build-tests \ + --verbose-build \ + --internal-build-type=shiboken2-generator + +The same can be used for the module, changing the value of ``internal-build-type`` to +``shiboken2-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 ``shiboken2`` from pip **does not** install ``shiboken2_generator``, +because the wheels are not on PyPi. + +You can get the ``shiboken2_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 \ + shiboken2 pyside2 shiboken2_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/shiboken2/doc/index.rst b/sources/shiboken2/doc/index.rst index 9403293ac..ebde8d1ff 100644 --- a/sources/shiboken2/doc/index.rst +++ b/sources/shiboken2/doc/index.rst @@ -1,39 +1,58 @@ -Shiboken the Binding Generator -******************************* +Shiboken +******** -Shiboken is the CPython-based binding code generator for C or C++ libraries. -It uses an ApiExtractor library to parse the C or C++ headers and get the -type information, using Clang. The library can also be used to parse non-Qt -projects. The following diagram summarizes Shiboken's role in the PySide -project. +.. ifconfig:: output_format == 'html' -.. image:: images/qtforpython-underthehood.png + Shiboken is a fundamental piece on the `Qt for Python <../index.html>`__ project that serves two purposes: -A typesystem file (XML) 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. Such actions are inevitable to -properly handle the data structures or types. +.. ifconfig:: output_format == 'qthelp' -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. + Shiboken is a fundamental piece on the `Qt for Python <../pyside2/index.html>`__ project that serves two purposes: -Table of contents -***************** + +* 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:: - :maxdepth: 1 - - overview.rst - samplebinding.rst - commandlineoptions.rst - projectfile.rst - typesystemvariables.rst - typeconverters.rst - codeinjectionsemantics.rst - sequenceprotocol.rst - ownership.rst - wordsofadvice.rst + :hidden: + :glob: + + gettingstarted.rst + shibokengenerator.rst shibokenmodule.rst - faq.rst typesystem.rst + examples/index.rst + considerations.rst diff --git a/sources/shiboken2/doc/overview.rst b/sources/shiboken2/doc/overview.rst deleted file mode 100644 index 97ef2c13c..000000000 --- a/sources/shiboken2/doc/overview.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _gen-overview: - -****************** -Generator Overview -****************** - -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. diff --git a/sources/shiboken2/doc/projectfile.rst b/sources/shiboken2/doc/projectfile.rst deleted file mode 100644 index aa703d941..000000000 --- a/sources/shiboken2/doc/projectfile.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. _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/shiboken2/doc/shiboken2.1 b/sources/shiboken2/doc/shiboken2.1 deleted file mode 100644 index e017bd9a9..000000000 --- a/sources/shiboken2/doc/shiboken2.1 +++ /dev/null @@ -1,73 +0,0 @@ -.TH SHIBOKEN "1" "March 2010" "shiboken v0.2.0" "User Commands" -.SH NAME -shiboken \- CPython bindings generator for C++ libraries -.SH DESCRIPTION -.SS "Usage:" -.IP -shiboken [options] header\-file typesystem\-file -.SS "General options:" -.TP -\fB\-\-debug\-level\fR=\fI[sparse\fR|medium|full] -Set the debug level -.TP -\fB\-\-documentation\-only\fR -Do not generates any code, just the documentation -.TP -\fB\-\-generatorSet\fR -generatorSet to be used. e.g. qtdoc -.TP -\fB\-\-help\fR -Display this help and exit -.TP -\fB\-\-include\-paths=\fR<path>[:<path>:...] -Include paths used by the C++ parser -.TP -\fB\-\-license\-file\fR=\fI[licensefile]\fR -File used for copyright headers of generated files -.TP -\fB\-\-no\-suppress\-warnings\fR -Show all warnings -.TP -\fB\-\-output\-directory\fR=\fI[dir]\fR -The directory where the generated files will be written -.TP -\fB\-\-silent\fR -Avoid printing any message -.TP -\fB\-\-typesystem\-paths=\fR<path>[:<path>:...] -Paths used when searching for typesystems -.TP -\fB\-\-version\fR -Output version information and exit -.SS "Shiboken options:" -.TP -\fB\-\-disable\-verbose\-error\-messages\fR -Disable verbose error messages. Turn the python code hard to debug but safe few kB on the generated bindings. -.TP -\fB\-\-enable\-parent\-ctor\-heuristic\fR -Enable heuristics to detect parent relationship on constructors. -.TP -\fB\-\-enable\-pyside\-extensions\fR -Enable PySide extensions, such as support for signal/slots, use this if you are creating a binding for a Qt\-based library. -.TP -\fB\-\-enable\-return\-value\-heuristic\fR -Enable heuristics to detect parent relationship on return values (USE WITH CAUTION!) -.SS "Shiboken options:" -.TP -\fB\-\-disable\-verbose\-error\-messages\fR -Disable verbose error messages. Turn the python code hard to debug but safe few kB on the generated bindings. -.TP -\fB\-\-enable\-parent\-ctor\-heuristic\fR -Enable heuristics to detect parent relationship on constructors. -.TP -\fB\-\-enable\-pyside\-extensions\fR -Enable PySide extensions, such as support for signal/slots, use this if you are creating a binding for a Qt\-based library. -.TP -\fB\-\-enable\-return\-value\-heuristic\fR -Enable heuristics to detect parent relationship on return values (USE WITH CAUTION!) -.SH COPYRIGHT -Copyright \(co 2016 The Qt Company Ltd. -.SH AUTHOR -.PP -This manpage was written for Debian, starting with a help2man output, by -Didier Raboud <didier@raboud.com>, on the 26. March 2010. diff --git a/sources/shiboken2/doc/commandlineoptions.rst b/sources/shiboken2/doc/shibokengenerator.rst index 19f614653..c3000ac09 100644 --- a/sources/shiboken2/doc/commandlineoptions.rst +++ b/sources/shiboken2/doc/shibokengenerator.rst @@ -1,3 +1,64 @@ +.. _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 @@ -8,7 +69,7 @@ Usage :: - shiboken [options] header-file typesystem-file + shiboken [options] header-file(s) typesystem-file Options @@ -62,7 +123,9 @@ Options ``--drop-type-entries="<TypeEntry0>[;TypeEntry1;...]"`` Semicolon separated list of type system entries (classes, namespaces, - global functions and enums) to be dropped from generation. + 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: @@ -184,3 +247,71 @@ QtDocGenerator Options ``--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/shiboken2/doc/typesystem.rst b/sources/shiboken2/doc/typesystem.rst index 7674129cd..0d43cec2c 100644 --- a/sources/shiboken2/doc/typesystem.rst +++ b/sources/shiboken2/doc/typesystem.rst @@ -1,5 +1,5 @@ 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. @@ -15,15 +15,51 @@ Below there is a complete reference guide to the various nodes (XML tags) of the 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 - typesystem_specifying_types - typesystem_manipulating_objects - typesystem_modify_function - typesystem_arguments - typesystem_solving_compilation - typesystem_templates - typesystem_conversionrule - typesystem_documentation +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/shiboken2/doc/typesystem_arguments.rst b/sources/shiboken2/doc/typesystem_arguments.rst index 28a5c80bc..bce0914e3 100644 --- a/sources/shiboken2/doc/typesystem_arguments.rst +++ b/sources/shiboken2/doc/typesystem_arguments.rst @@ -119,7 +119,8 @@ 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. The ``owner`` attribute + 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. diff --git a/sources/shiboken2/doc/typesystem_codegeneration.rst b/sources/shiboken2/doc/typesystem_codegeneration.rst new file mode 100644 index 000000000..fb41e28e1 --- /dev/null +++ b/sources/shiboken2/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/shiboken2/doc/codeinjectionsemantics.rst b/sources/shiboken2/doc/typesystem_codeinjection.rst index beb2997a3..b0d5f3851 100644 --- a/sources/shiboken2/doc/codeinjectionsemantics.rst +++ b/sources/shiboken2/doc/typesystem_codeinjection.rst @@ -1,8 +1,10 @@ +.. _codeinjectionsemantics: + ************************ Code Injection Semantics ************************ -:std:doc:`API Extractor <overview>` provides the +: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 @@ -17,99 +19,87 @@ This is the ``inject-code`` tag options that matters to |project|. </inject-code> -Conventions -=========== - -**C++ Wrapper** - This term refers to a generated C++ class that extends a class from the - wrapped library. It is used only when a wrapped C++ class is polymorphic, - i.e. it has or inherits any virtual methods. - -**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. - -**Native** - This is a possible value for the ``class`` attribute of the ``inject-code`` - tag, it means things more akin to the C++ side. - -**Target** - Another ``class`` attribute value, it indicates things more close to the - Python side. - inject-code tag =============== The following table describes the semantics of ``inject-code`` tag as used on -|project|. - - +---------------+------+---------+--------------------------------------------------------------+ - |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 |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. | - +---------------+------+---------+--------------------------------------------------------------+ +|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 @@ -395,3 +385,6 @@ to prevent bad custom code to pass unnoticed. (...) // 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/shiboken2/doc/typeconverters.rst b/sources/shiboken2/doc/typesystem_converters.rst index 872daa187..872daa187 100644 --- a/sources/shiboken2/doc/typeconverters.rst +++ b/sources/shiboken2/doc/typesystem_converters.rst diff --git a/sources/shiboken2/doc/typesystem_manipulating_objects.rst b/sources/shiboken2/doc/typesystem_manipulating_objects.rst index c04a4fa27..d87b816a3 100644 --- a/sources/shiboken2/doc/typesystem_manipulating_objects.rst +++ b/sources/shiboken2/doc/typesystem_manipulating_objects.rst @@ -36,7 +36,8 @@ inject-code The ``class`` attribute specifies which module of the generated code that - will be affected by the code injection. The ``class`` attribute accepts the + will be affected by the code injection + (see :ref:`codegenerationterminology`). The ``class`` attribute accepts the following values: * native: The c++ code @@ -62,6 +63,8 @@ inject-code will be extracted. + For a detailed description, see :ref:`codeinjectionsemantics`. + modify-field ^^^^^^^^^^^^ @@ -103,6 +106,7 @@ modify-function access="public | private | protected" allow-thread="true | auto | false" exception-handling="off | auto-off | auto-on | on" + overload-number="number" rename="..." /> </object-type> @@ -119,6 +123,7 @@ modify-function 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 @@ -131,6 +136,47 @@ modify-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`. @@ -160,7 +206,7 @@ add-function Within the signature, names for the function parameters can be specified by enclosing them within the delimiter *@*: - .. code-block:: c++ + .. code-block:: void foo(int @parameter1@,float) @@ -187,3 +233,78 @@ conversion-rule .. 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/shiboken2/doc/ownership.rst b/sources/shiboken2/doc/typesystem_ownership.rst index 59fdb9d66..a2ee8e1fa 100644 --- a/sources/shiboken2/doc/ownership.rst +++ b/sources/shiboken2/doc/typesystem_ownership.rst @@ -1,3 +1,5 @@ +.. _objectownership: + **************** Object ownership **************** @@ -154,6 +156,9 @@ Not saving unowned objects references Ownership Management in the Typesystem ======================================= +For the possible values of the ``class`` attribute, see +:ref:`codegenerationterminology`. + Ownership transfer from C++ to target ------------------------------------- @@ -224,4 +229,6 @@ call returned. In this case, you should use the ``invalidate-after-use`` attribu In this example the second argument will be invalidated after this method call. -.. [#] See *Object Trees and Object Ownership* http://doc.qt.io/qt-5/objecttrees.html +See `Object Trees and Object Ownership`_. + +.. _`Object Trees and Object Ownership`: http://doc.qt.io/qt-5/objecttrees.html diff --git a/sources/shiboken2/doc/sequenceprotocol.rst b/sources/shiboken2/doc/typesystem_sequenceprotocol.rst index 26ae3b220..742be3d70 100644 --- a/sources/shiboken2/doc/sequenceprotocol.rst +++ b/sources/shiboken2/doc/typesystem_sequenceprotocol.rst @@ -22,7 +22,7 @@ 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 -:doc:`inject-code <codeinjectionsemantics>` tag. +: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 diff --git a/sources/shiboken2/doc/typesystem_specifying_types.rst b/sources/shiboken2/doc/typesystem_specifying_types.rst index ac1121461..221519541 100644 --- a/sources/shiboken2/doc/typesystem_specifying_types.rst +++ b/sources/shiboken2/doc/typesystem_specifying_types.rst @@ -104,6 +104,7 @@ primitive-type <typesystem> <primitive-type name="..." since="..." + until="..." target-name="..." default-constructor="..." preferred-conversion="yes | no" /> @@ -114,7 +115,11 @@ primitive-type 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 of this type. + 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++ @@ -148,7 +153,9 @@ namespace-type <typesystem> <namespace-type name="..." + visible="true | auto | false" generate="yes | no" + generate-using="yes | no" package="..." since="..." revision="..." /> @@ -156,8 +163,23 @@ namespace-type The **name** attribute is the name of the namespace, e.g., "Qt". - The *optional* **generate** attribute is used to inform if you need to prepend - the given namespace into each generated class. Its default value is **yes**. + 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. @@ -321,30 +343,7 @@ object-type interface-type ^^^^^^^^^^^^^^ - The interface-type node indicates that the given class is replaced by an - interface pattern when mapping from C++ to the target language. Using the - interface-type node implicitly makes the given type an :ref:`object-type`. - - .. code-block:: xml - - <typesystem> - <interface-type name="..." - since="..." - package ="..." - default-superclass ="..." - revision="..." /> - </typesystem> - - The **name** attribute is the fully qualified C++ class name. The *optional* - **package** attribute can be used to override the package of the type system. - If there is no C++ base class, the *optional* **default-superclass** attribute - can be used to specify a superclass in the generated target language API, for - the given class. - - The *optional* **since** value is used to specify the API version of this interface. - - The **revision** attribute can be used to specify a revision for each type, easing the - production of ABI compatible bindings. + This type is deprecated and no longer has any effect. Use object-type instead. .. _container-type: @@ -431,6 +430,14 @@ smart-pointer-type 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> @@ -438,7 +445,8 @@ smart-pointer-type since="..." type="..." getter="..." - ref-count-method="..."/> + ref-count-method="..." + instantiations="..."/> </typesystem> .. _function: @@ -462,3 +470,20 @@ function 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/shiboken2/doc/typesystemvariables.rst b/sources/shiboken2/doc/typesystem_variables.rst index 73d4dd12c..73d4dd12c 100644 --- a/sources/shiboken2/doc/typesystemvariables.rst +++ b/sources/shiboken2/doc/typesystem_variables.rst |
