[RU](README.ru.md) | [**EN**](README.md)

---

# Document Converter

<a name="Description"></a>
## Description

This project provides an example application for document conversion.

The application demonstrates how to work with LibreOffice.

The application allows to: 
- Convert documents to `xlsx`, `ods` or `pdf` formats.

The project uses `cairo`, `hunspell`, `libepoxy`, `liblangtag` and `libreoffice` library dependencies.

Build status:

1. example - [![pipeline status](https://hub.mos.ru/auroraos/examples-extra/DocumentConverter/badges/example/pipeline.svg)](https://hub.mos.ru/auroraos/examples-extra/DocumentConverter/-/commits/example)
2. dev - [![pipeline status](https://hub.mos.ru/auroraos/examples-extra/DocumentConverter/badges/dev/pipeline.svg)](https://hub.mos.ru/auroraos/examples-extra/DocumentConverter/-/commits/dev)

<a name="Table-of-contents"></a>

## Table of contents

1. [Compatibility](#Compatibility)

2. [Build features](#Build-features)

3. [Branches info](#Branches-info)
4. [Install and run](#Install-and-run)
5. [Screenshots](#Screenshots)
6. [Use cases](#Use-cases)

7. [Known errors and restrictions](#Known-errors-and-restrictions)

8. [Project structure](#Project-structure)
9. [Terms of use and participation in development](#Terms-of-use-and-participation-in-development)

<a name="Compatibility"></a>

## Compatibility

The project is compatible with all the current versions of the Aurora OS.

<a name="Build-features"></a>
## Build features

### Clear building

1. Make sure that you have 32 GB of RAM and SDK with docker (don't use VB for building this example).

2. Open a terminal or command prompt.
3. Navigate to the directory that contains your Git repository.
4. Execute the command "git lfs pull" to download any files tracked by LFS.
5. Execute the command "git submodule update --init --depth 1" to update and initialize submodules in the repository.
6. Execute the command "mb2 -t AuroraOS-5.1.5.105-base-armv7hl build-init" to initialize the build environment.
7. Execute the command "mb2 -t AuroraOS-5.1.5.105-base-armv7hl prepare" to apply the patches needed for the build.
8. Execute the command "mb2 -t AuroraOS-5.1.5.105-base-armv7hl build" to start building the package.
9. Execute the command to sign the rpm-package:

```
sfdk engine exec rpmsign-external sign  \
    --key absolute/path/to/key/file.pem \
    --cert absolute/path/to/cert/file.pem \
      absolute/path/to/rpm/package.rpm
```
The target rpm-package is in the RPMS directory of the project.

### Solutions of possible problems

If building is failed with the next error
```
+ aclocal -I <path/to>/DocumentConverter/upstream/m4
autom4te: error: need GNU m4 1.4 or later: /usr/bin/m4
aclocal: error: echo failed with exit status: 1
```
then enter into the target and install the m4 dependency manually.

### Repeated building for another target

The build is run in the same directory as the application sources so it's necessary to delete the previous building results before a new build for another target.

It's possible to use the script `clear_build_results.sh <old target>`.
To use the script it's needed to connect to the build engine and to the previous build target.

Next it's needed to invoke the script and specify the previous build target name:

```

./clear_build_results.sh AuroraOS-5.1.5.105-base-armv7hl

```

Or it's possible to do manually. Run the next commands from the project root directory:

1. `rm -fr libs_build`
2. `rm -fr upstream/workdir`
3. `rm -f application/Makefile`
4. `cd libs/liblangtag && make distclean`

<a name="Branches-info"></a>
## Branches info

[Branches](https://developer.auroraos.ru/doc/software_development/examples#branches)

<a name="Install-and-run"></a>
## Install and run

The RPM package created in the [Build features](#Build-features) section needs to be uploaded to your device and installed like any other RPM package.

<a name="Screenshots"></a>

## Screenshots

![Screenshots](screenshots/screenshots.png)

<a name="Use-cases"></a>
## Use cases

### Document conversion

* To convert a document, press and hold the line with the required file to convert from the main application screen.
* Select desired output format from the context menu.

<a name="Known-errors-and-restrictions"></a>
## Known errors and restrictions

LibreOffice in this implementation does not support simultaneous work in multiple threads. Attempting to initialize the Office object while another process is running may delay initialization until the current conversion is complete or cause the application to crash.

<a name="Project-structure"></a>

## Project structure

The project has a standard structure
of an application based on C++ and QML for Aurora OS.

* **[application](application)** directory contains the application source code:
  * **[application.pro](application/application.pro)** file
describes the structure of the application for the qmake build system.
  * **[icons](application/icons)** directory contains the application icons for different screen resolutions.
  * **[qml](application/qml)** directory contains the QML source code and the UI resources.
    * **[cover](application/qml/cover)** directory contains the application cover implementations.
    * **[icons](application/qml/icons)** directory contains the additional custom UI icons.
    * **[pages](application/qml/pages)** directory contains the application pages.
    * **[DocumentConverter.qml](application/qml/DocumentConverter.qml)** file
provides the application window implementation.
  * **[translations](application/translations)** directory contains the UI translation files.
  * **[src](application/src)** directory contains the C++ source code.
    * **[main.cpp](application/src/main.cpp)** file is the application entry point.
  * **[ru.auroraos.DocumentConverter.desktop](application/ru.auroraos.DocumentConverter.desktop)** file
defines the display and parameters for launching the application.
* **[rpm](rpm)** directory contains the rpm-package build settings.
  * **[ru.auroraos.DocumentConverter.spec](rpm/ru.auroraos.DocumentConverter.spec)** file is used by rpmbuild tool.
* **[ru.auroraos.DocumentConverter.pro](application/ru.auroraos.DocumentConverter.pro)** file
describes the project that contains two subprojects where the first is responsible
for building the libreoffice, and the second describes the structure of the application for
the qmake build system.
* **[upstream](upstream)** directory contains source code LibreOffice (git submodule).
* **[tarballs](tarballs)** directory of dependencies in the form of archives necessary for the build LibreOffice.
* **[libs](libs)** directory of dependencies in the form of source codes necessary for the build LibreOffice.
  * **[cairo-1.17.4](libs/cairo-1.17.4)** directory contains the [Cairo](https://gitverse.ru/auroraos/mirror_cairo) library source code.
  * **[hunspell-1.7.0](libs/hunspell-1.7.0)** directory contains the [Hunspell 1.7.0](https://gitverse.ru/auroraos/mirror_hunspell/tag/v1.7.0) library source code.
  * **[libepoxy-1.5.9](libs/libepoxy-1.5.9)** directory contains the [Epoxy 1.5.9](https://gitverse.ru/auroraos/mirror_libepoxy/tag/1.5.9) library source code.
  * **[liblangtag](libs/liblangtag)** directory contains the [liblangtag](https://gitverse.ru/auroraos/mirror_liblangtag) library source code.

<a name="Terms-of-use-and-participation-in-development"></a>
## Terms of use and participation in development

The source code of the project is provided under [the license](LICENSE.BSD-3-Clause.md),
which allows its use in third-party applications.

[Contributor License Agreement](https://gitlab.com/omprussia/wiki/-/wikis/CLA)

The [contributor agreement](CONTRIBUTING.md) documents the rights granted by contributors
of the Open Mobile Platform.

Information about the contributors is specified in the [AUTHORS](AUTHORS.md) file.

[Code of conduct](CODE_OF_CONDUCT.md) is a current set of rules of the Open Mobile
Platform which informs you how we expect the members of the community will interact
while contributing and communicating.