Metadata-Version: 2.5
Name: toga_tml
Version: 0.2.1
Summary: Markup Language for Toga
Project-URL: Homepage, https://github.com/ZeusyBoy98/TML
Author-email: ZeusyBoy <wetcementstudios@gmail.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: compiler,gui,markup language,toga,ui
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# TML

<!-- rumdl-disable MD013 -->
[![Python Versions](https://img.shields.io/pypi/pyversions/toga.svg)](https://pypi.python.org/pypi/toga-tml)
[![License](https://img.shields.io/pypi/l/toga-tml)](https://github.com/ZeusyBoy98/TML/blob/main/LICENSE)
[![PyPI Version](https://img.shields.io/pypi/v/toga-tml)](https://pypi.python.org/pypi/toga-tml)
[![Project status](https://img.shields.io/pypi/status/toga-tml)](https://pypi.python.org/pypi/toga-tml)
[![Build Status](https://github.com/ZeusyBoy98/TML/actions/workflows/python-publish.yml/badge.svg)](https://github.com/ZeusyBoy98/TML/actions/workflows/python-publish.yml)
![Repo Size](https://img.shields.io/github/repo-size/ZeusyBoy98/TML)
<!-- rumdl-enable MD013 -->

![TML Logo](https://raw.githubusercontent.com/ZeusyBoy98/TML/refs/heads/main/logo.png)

## Toga Markup Language
A markup language for the Toga Python framework. Allows you to build cross-platform GUIs in Python, but with an XML tag syntax.

## Documentation
Read the full docs here: [TML Docs](https://tml.zeusyboy.com)

## Why
The Toga framework for Python is really cool. It lets you make cross-platform user interfaces that you can use with BeeWare, and I really want to learn it and use it. When I started using it, I was immediately put off by how it makes the UI. It feels like making a whole website using just the JavaScript DOM. So I had the idea to build a markup language like HTML that I could use with Toga and BeeWare to make development so much easier for myself.

## Requirements
The TML requirements are the same as the Toga requirements, and it obviously requires Toga itself. Platform specifics can be seen here: [Toga Platform Requirements](https://toga.beeware.org/en/latest/reference/platforms/)

## Installation
In your Toga project's pyproject.toml, add:
```toml
requires = [
    "toga-tml",
]
``` 
In any python files in that project you want to use toga in, add the following code:
```python
import toga_tml
# ... other imports

class Example(toga.App):
    def startup(self):
        # ... other toga code
        self.main_window = toga.MainWindow(title=self.formal_name)
        # This can be changed depending on where your .xml or .tml file is
        tml_path = pathlib.Path(__file__).parent / "YOUR_XML_OR_TML_FILE_HERE" 
        self.main_window.content = toga_tml.load(tml_path, self=self)
        self.main_window.show()
    # ... other functions
```
Then run `briefcase dev -r` to run the project and rebuild dependencies.

## Usage
The syntax for TML is similar to HTML, except it uses Toga attributes and tag names. An example can be seen here:
```xml
<Import from="toga.style" import="Pack"/>

<!-- This is a comment -->
<Prefabs>
    <RedHi "Hello world" type="Label" style=Pack(color="#ff0000")/>
</Prefabs>

<Body>
    <RedHi name="hi_label"/>
    <Box name="input_container"> 
        <TextInput name="name_input" flex=1/>
        <Button "Click me!" name="button" on_press=self.say_hello margin=5/>
    </Box>
</Body>
```
- Imports must be put in self closing tags at the top of a TML file. The syntax is `<Import from="location" import="thing"/>` The quotes are optional, `from=location import=thing` is also valid TML code.
- TML comments are the same as HTML comments, they can be single line or multi-line, but they cannot go inside of other code.
- Prefabs let you define tags that you can use later with preset arguments and attributes. They must be defined in the `<Prefabs></Prefabs>`. Any prefab you use in the Body has to have a `name=""` attribute to distinguish it from other uses of that prefab.
- All TML user interface code should be inside the `<Body></Body>` tags. 
- If you want to be able to refer to a TML element in a python file, a `name=""` must be added, and then you can refer to it with `self.name`. 
- All TML tags are self closing, except for `<Body></Body>` and `<Box></Box>`. This means that when using a label or a button, text that will be displayed on it must go in quotes after the tag opening, called the "argument" e.g. `<Label "Hello"/>`. 
- Any Toga attributes you wish to use in a tag can go after the argument, or if you don't have an argument, after the tag opening. The syntax for attributes will be the same as Toga syntax, except no commas separating attributes e.g. `<Label "Hi" name="label1" margin=5/>`.