.. currentmodule:: qte


UIs and Resources
=================

PySide's resource system relies on compiling all resource files before using
them, which goes against the normal python workflow.  To improve upon this,
`qte` provides functions to dynamically load resources and user interfaces.


Working with Resources
----------------------

Resources should be handled in a similar with `qte` as with Qt; all resources
should be stored in a location referenced by a *qrc* file.  In Qt, this would
usually be compiled into a binary resource file when the code is compiled.
In `qte`, it is preferable not to compile anything, so the files are read
directly.  The `loadResource` function parses a *qrc* file and loads all
referenced resources into the Qt resource system, so that they can be loaded
using normal Qt syntax (e.g. ``QIcon(':myicon.png')``).


Working with UIs
----------------

*ui* files created with Qt Designer can be loaded in several
different ways, depending on their usage.  The simplest way is to
create a new instance of the widget defined in the file by calling `loadUi`.
However, if the widget requires further customisation then it is preferable
to create a new widget class rather than an instance.  This can be done
with the `uiWrapper` function.


Resource file reference
-----------------------

The specification for rcc files is not documented, but from a study of the rcc
source code, it appears that this is the format:  The file is binary and
consists of four sections, in order.


Header
^^^^^^

This is general information about the file.

======== ==== ======== ===================================================
Position Size Value    Description
======== ==== ======== ===================================================
0        4    "qres"   Magic number
4        4    0x01     RCC version.  This is always 0x01
8        4    t_off    Position of start of Tree section (usually 20)
12       4    d_off    Position of start of Data section
                       (= n_off + len(names))
16       4    n_off    Position of start of Name section
                       (= t_off + len(tree))
======== ==== ======== ===================================================


Tree
^^^^

The Tree section contains information about the relative positions of
files and directories in the resource tree.  It is a sequence of records,
sorted by the hash of the node name in each branch.  For example:

| root
|  - a
|  - b
|    -a
|    -c
|  -c

The structure of each node depends on whether if references a file or a
directory.  For directories (including root):

======== ==== ========= ===================================================
Position Size Value     Description
======== ==== ========= ===================================================
0        4    n_off     Offset of name record in the Names section
4        2    flags     A bitwise OR combination of flags. 0x1 indicates
                        a compressed file.  0x2 indicates a directory.
6        4    c_child   The number of children nodes in the tree.  The
                        children records will follow this node.
10       4    c_off     The index position of the node in the list of
                        nodes.  *root* is always 1 and they are numbered
                        sequentially, including file nodes (although
                        the number is not recorded for file nodes).
======== ==== ========= ===================================================

For files:

======== ==== ========= ===================================================
Position Size Value     Description
======== ==== ========= ===================================================
0        4    n_off     Offset of name record in the Names section
4        2    flags     A bitwise OR combination of flags. 0x1 indicates
                        a compressed file.  0x2 indicates a directory.
                        Normal files are either 0x0 or 0x1.
6        2    l_cntry   The locale's country code as specified in
                        `!QLocale`.  The locale defaults to C.
8        2    l_lang    The locale's language code as  specified in
                        `!QLocale`.  The locale defaults to C.
10       4    c_off     The node's offset in the Data section.
======== ==== ========= ===================================================


Names
^^^^^

This section contains a list of node names, in the same order as they
appear in the Tree section.

======== ============ ========= ===========================================
Position Size         Value     Description
======== ============ ========= ===========================================
0        2            c_name    The length of the name.
4        8            h_name    The hash of the name (calculated using
                                `!qHash`).
8        2 * c_name   name      The name, encoded in unicode as 2-bytes
                                per character.
======== ============ ========= ===========================================


Data
^^^^

This is the actual data in the resources and only applies to files, not
directories.

======== ======== ========= ==============================================
Position Size     Value     Description
======== ======== ========= ==============================================
0        4        l_data    The length of the data.
4        l_data   data      The data contained in the resource, compressed
                            if the appropriate flag is set in the Tree
                            section.
======== ======== ========= ==============================================