### Python API Setup Example

Source: https://dooit-org.github.io/dooit/configuration/dooit_api.html

This snippet demonstrates how to set up the Dooit API within a Python script using the `@subscribe` decorator for the `Startup` event. It shows a placeholder for calling an API function.

```python
from dooit.api.core import DooitAPI
from dooit.api.events import Startup

@subscribe(Startup)
def setup(api: DooitAPI, _):
    api.<Your function here>
```

--------------------------------

### Setup Dooit Status Bar with Nord Theme

Source: https://dooit-org.github.io/dooit-extras/configs/config1.html

Configures the status bar for Dooit using widgets like Mode, Spacer, StatusIcons, TextBox, and Clock, styled with the 'Nord Theme'. This setup is executed upon application startup.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from rich.style import Style
from dooit_extras.formatters import *
from dooit_extras.bar_widgets import *
from dooit_extras.scripts import *
from rich.text import Text


@subscribe(Startup)
def setup_bar(api: DooitAPI, _):
    theme = api.vars.theme

    widgets = [
        Mode(api),
        Spacer(api, width=0),
        StatusIcons(api, bg=theme.background2),
        TextBox(api, text="  ", bg=theme.primary),
        TextBox(api, text=" -4°C ", fg=theme.foreground3, bg=theme.background3),
        TextBox(api, text=" 󰥔 ", bg=theme.primary),
        Clock(api, format="%I:%M %p", fg=theme.foreground3, bg=theme.background3),
    ]
    api.bar.set(widgets)
```

--------------------------------

### Setup Dooit Formatters with Nord Theme

Source: https://dooit-org.github.io/dooit-extras/configs/config1.html

Configures various formatters for Dooit tasks and workspaces using the 'Nord Theme'. It adds custom descriptions, status icons, urgency indicators, due date formatting, and tag highlighting. This function is triggered on application startup.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from rich.style import Style
from dooit_extras.formatters import *
from dooit_extras.bar_widgets import *
from dooit_extras.scripts import *
from rich.text import Text


@subscribe(Startup)
def setup_formatters(api: DooitAPI, _):
    fmt = api.formatter
    theme = api.vars.theme

    # ------- WORKSPACES ------- 
    format = Text(" ({}) ", style=theme.primary).markup
    fmt.workspaces.description.add(description_children_count(format))

    # --------- TODOS --------- 
    # status formatter
    fmt.todos.status.add(status_icons(completed=" ", pending="󰞋 ", overdue="󰅗 "))

    # urgency formatte
    u_icons = {1: "  󰎤", 2: "  󰎧", 3: "  󰎪", 4: "  󰎭"}
    fmt.todos.urgency.add(urgency_icons(icons=u_icons))

    # due formatter
    fmt.todos.due.add(due_casual_format())
    fmt.todos.due.add(due_icon(completed=" ", pending=" ", overdue=" "))

    # description formatter
    format = Text("  {completed_count}/{total_count}", style=theme.green).markup
    fmt.todos.description.add(todo_description_progress(fmt=format))
    fmt.todos.description.add(description_highlight_tags(fmt=" {}"))
```

--------------------------------

### Setup Dooit Dashboard with Nord Theme

Source: https://dooit-org.github.io/dooit-extras/configs/config1.html

Initializes the Dooit dashboard with a custom header, ASCII art, and the current date, all styled using the 'Nord Theme'. This function is called during the application's startup sequence.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from rich.style import Style
from dooit_extras.formatters import *
from dooit_extras.bar_widgets import *
from dooit_extras.scripts import *
from rich.text import Text


@subscribe(Startup)
def setup_dashboard(api: DooitAPI, _):
    from datetime import datetime

    theme = api.vars.theme

    now = datetime.now()
    formatted_date = now.strftime(" 󰸘 %A, %d %b ")

    header = Text(
        "I alone shall stand against the darkness of my overdue tasks",
        style=Style(color=theme.primary, bold=True, italic=True),
    )

    ascii_art = r"""
                     .
                    / V\
                  / `  /
                 <<   |
                 /    |
               /      |
             /        |
           /    \  \ /
          (      ) | |
  ________|   _/_  | |
<__________\______)\__)
    """

    items = [
        header,
        "",
        Text(ascii_art, style=api.vars.theme.primary),
        "",
        Text(
            formatted_date,
            style=Style(color=theme.secondary, bold=True, italic=True),
        ),
    ]
    api.dashboard.set(items)
```

--------------------------------

### Install Dooit globally with Pixi

Source: https://dooit-org.github.io/dooit/getting_started/installation.html

Installs Dooit globally using Pixi, a package and environment manager. This makes Dooit accessible from any directory.

```bash
pixi global install dooit
```

--------------------------------

### NixOS Home Manager Installation for Dooit

Source: https://dooit-org.github.io/dooit/getting_started/installation.html

Configures Dooit and Dooit Extras for Home Manager on NixOS using flakes. This involves setting up `flake.nix` and the Home Manager configuration in `home-manager/dooit.nix`.

```nix
# flake.nix

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    dooit.url = "github:dooit-org/dooit";
    dooit-extras.url = "github:dooit-org/dooit-extras";
  };
  # ...

  outputs = inputs @ {
    nixpkgs,
    ...
  };
    let
      pkgs = import nixpkgs {};
      system = "x86_64-linux"; # change to whatever your system should be
    in {
      homeConfigurations."${username}" = nixpkgs.lib.nixosSystem {
        pkgs = pkgs;
        extraSpecialArgs = {
          inherit system inputs;
        };
 
        modules = [
          ./home-manager/dooit.nix
        ];
      };
    };
  }
}

```

```nix
# home-manager/dooit.nix

{
  inputs,
  pkgs,
  ...
}:
{
  imports = [
    # home manager module for dooit
    inputs.dooit.homeManagerModules.default
  ];

  # adds dooit-extras to pkgs
  nixpkgs.overlays = [inputs.dooit-extras.overlay];

  programs.dooit = {
    enable = true;
    extraPackages = [pkgs.dooit-extras];
  };
}

```

--------------------------------

### Install Dooit with yay on Arch Linux

Source: https://dooit-org.github.io/dooit/getting_started/installation.html

Installs Dooit and Dooit Extras on Arch Linux using the `yay` AUR helper. This command fetches packages from the Arch User Repository.

```bash
yay -S dooit dooit-extras
```

--------------------------------

### Install Dooit with pip

Source: https://dooit-org.github.io/dooit/getting_started/installation.html

Installs Dooit and Dooit Extras using pip, the Python package installer. This is a common method for Python projects.

```bash
pip install dooit dooit-extras
```

--------------------------------

### Setup Dashboard with Python

Source: https://dooit-org.github.io/dooit/extra/moving_from_v2.html

Illustrates how to set up the dashboard in Dooit V3 using Python. It includes creating colored text elements and defining the dashboard layout, utilizing the new API for setting the dashboard content.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from rich.text import Text


@subscribe(Startup)
def dashboard_setup(api: DooitAPI, _):

    def colored(text, color):
        return Text(text, style = color).markup

    theme = api.vars.theme

    ART = "some ascii art"
    NL = " \n"
    SEP = Text("─" * 60, "d " + theme.background3)
    help_message = f"Press {colored('?', magenta)} to spawn help menu"
    DASHBOARD = [ART, NL, SEP, NL, NL, NL, help_message]

    api.dashboard.set(DASHBOARD)
```

--------------------------------

### NixOS Module Installation for Dooit

Source: https://dooit-org.github.io/dooit/getting_started/installation.html

Configures Dooit and Dooit Extras within a NixOS system using flakes. This involves defining inputs in `flake.nix` and configuring modules in `dooit.nix`.

```nix
# flake.nix

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    dooit.url = "github:dooit-org/dooit";
    dooit-extras.url = "github:dooit-org/dooit-extras";
  };
  # ...

  outputs = inputs @ {
    nixpkgs,
    ...
  };
    let
      pkgs = import nixpkgs {};
      system = "x86_64-linux"; # change to whatever your system should be
    in {
      nixosConfigurations."${host}" = nixpkgs.lib.nixosSystem {
        specialArgs = {
          inherit system inputs pkgs;
        };
        modules = [
          ./dooit.nix
        ];
      };
    };
  }
}

```

```nix
# dooit.nix

{
  inputs,
  pkgs,
  ...
}:
let
  mydooit = pkgs.dooit.override {
    extraPackages = [
      pkgs.dooit-extras
    ];
  };
in {

  # this overlay allows you to use dooit from pkgs.dooit
  nixpkgs.overlays = [inputs.dooit.overlay inputs.dooit-extras.overlay];

  environment.systemPackages = [
    mydooit
  ];
}

```

--------------------------------

### Start Search in Dooit

Source: https://dooit-org.github.io/dooit/configuration/dooit_api.html

The `start_search` method initiates the search functionality within the Dooit list, allowing users to find specific items.

```python
api.start_search()
```

--------------------------------

### Multiple Key Binding for Same Function in Python

Source: https://dooit-org.github.io/dooit/configuration/keys.html

Shows how to assign multiple keys to the same function in Python. This is useful for accommodating different keyboard layouts or user preferences. For example, both '=' and '+' can be used to increase urgency.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup

@subscribe(Startup)
def setup(api: DooitAPI, _):
    api.keys.set(["=","+"], api.increase_urgency)
    api.keys.set(["-","_"], api.decrease_urgency)
```

--------------------------------

### Start Sorting in Dooit

Source: https://dooit-org.github.io/dooit/configuration/dooit_api.html

The `start_sort` method begins the sorting process for the siblings of the currently highlighted item, allowing for reordering of elements.

```python
api.start_sort()
```

--------------------------------

### Install Dooit with Conda/Mamba

Source: https://dooit-org.github.io/dooit/getting_started/installation.html

Installs Dooit and Dooit Extras using Conda or Mamba package managers. These are common in data science and scientific computing environments.

```bash
conda install dooit dooit-extras
```

```bash
mamba install dooit dooit-extras
```

--------------------------------

### Configure Dooit Layouts with Python Widgets

Source: https://dooit-org.github.io/dooit/configuration/layout.html

This snippet demonstrates how to import necessary widgets and API components from the dooit library to configure workspace and todo layouts. It uses the `@subscribe` decorator to trigger layout setup on application startup, defining the order and inclusion of columns like description, status, recurrence, due date, and urgency.

```python
from dooit.ui.api.widgets import TodoWidget, WorkspaceWidget
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup

@subscribe(Startup)
def layout_setup(api: DooitAPI, _):
    api.layouts.workspace_layout = [WorkspaceWidget.description]

    api.layouts.todo_layout = [
        TodoWidget.status,
        TodoWidget.description, 
        TodoWidget.recurrence,
        TodoWidget.due,
        TodoWidget.urgency,
    ]
```

--------------------------------

### Changing Dooit Theme (Python)

Source: https://dooit-org.github.io/dooit/configuration/theme.html

Shows how to change the active theme in Dooit by importing a theme from `dooit_extras.themes` and setting it using `api.css.set_theme()`. This requires the `dooit_extras` package to be installed.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from dooit_extras.themes import Gruvbox

@subscribe(Startup)
def layout_setup(api: DooitAPI, _):
    api.css.set_theme(Gruvbox)
```

--------------------------------

### Highlight Words Starting with '!' in Description

Source: https://dooit-org.github.io/dooit/configuration/formatter.html

A Python function that highlights words starting with '!' in a description string using Rich Text. It utilizes regular expressions and the Dooit API's theme for styling. This formatter is suitable for emphasizing specific parts of a description.

```python
from dooit.api import Todo
from dooit.ui.api import DooitAPI
from rich.text import Text

def redify_important(description: str, model: Todo, api: DooitAPI) -> Text:
    regex = r"!([\w]+)"
    text = Text(description)
    text.highlight_regex(regex, style = api.vars.theme.red)
    return text
```

--------------------------------

### Urgency Icons Formatter Configuration (Python)

Source: https://dooit-org.github.io/dooit-extras/formatters/urgency.html

Defines example configurations for icons and colors used by the Urgency Icons formatter. The icons are represented by Unicode characters, and colors can be mapped using theme variables. These dictionaries are used to customize the visual representation of todo urgency levels.

```python
{
    "1": "󰲠",
    "2": "󰲢",
    "3": "󰲤",
    "4": "1"
}
```

```python
{
    "1": theme.green,
    "2": theme.yellow,
    "3": theme.orange,
    "4": theme.red
}
```

--------------------------------

### Add Custom Formatters to Dooit

Source: https://dooit-org.github.io/dooit/configuration/formatter.html

A Python code snippet demonstrating how to add custom formatters to Dooit's workspace and todo items. It uses the `subscribe` decorator to run the formatter setup on application startup and accesses the formatter API to add previously defined formatter functions.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from rich.text import Text

@subscribe(Startup)
def set_formatters(api: DooitAPI, _):
    fmt = api.formatter

    fmt.workspaces.description.add(redify_important)
    fmt.todos.description.add(redify_important)
    fmt.todos.due.add(my_custom_due)
```

--------------------------------

### Todo Property - Tags

Source: https://dooit-org.github.io/dooit/backend/todo.html

A property that returns a list of all tags associated with the todo. Tags are identified as words starting with the '@' symbol within the todo's description or content.

```python
tags -> List[str]

Returns all the tags in the todo (words starting with `@`)
**Returns:**
Type| Default| Description  
---|---|---  
List[str]| | List of the tags  
```

--------------------------------

### Add Highlight Tags Formatter to Dooit Descriptions

Source: https://dooit-org.github.io/dooit-extras/formatters/description.html

This formatter highlights tags (words starting with '@') in the description. It allows customization of the highlight color and the format used to display the tags. The formatter is added to the Dooit API during startup.

```python
from dooit_extras.formatters import description_highlight_tags
from dooit.ui.api.events import subscribe, Startup

@subscribe(Startup)
def setup(api, _):
    # ...
    api.formatter.workspaces.description.add(description_highlight_tags())
    api.formatter.todos.description.add(description_highlight_tags())
    # ...
```

--------------------------------

### Basic Key Binding in Python

Source: https://dooit-org.github.io/dooit/configuration/keys.html

Demonstrates how to bind a single key to a specific function using the `api.keys.set` method in Python. This is useful for customizing user interactions within the application. The `description` and `group` parameters are optional.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup

@subscribe(Startup)
def setup(api: DooitAPI, _):
    api.keys.set("j", api.move_down, "my custom vim keys")
    api.keys.set("k", api.move_up, "my custom vim keys")
```

--------------------------------

### Update Color Configuration with Python

Source: https://dooit-org.github.io/dooit/extra/moving_from_v2.html

Demonstrates the new color theming API in Dooit V3 using Python. It shows how to subscribe to startup events and access theme variables via the DooitAPI.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup

@subscribe(Startup)
def foo(api: DooitAPI, _):
    theme = api.vars.theme
```

--------------------------------

### Dooit Keybindings: New Implementation with API

Source: https://dooit-org.github.io/dooit/extra/moving_from_v2.html

Demonstrates the modern approach to setting keybindings in Dooit using the `DooitAPI` and the `@subscribe` decorator. This allows for more complex and dynamic key assignments, including direct calls to API functions.

```python
@subscribe(Startup)
def key_setup(api: DooitAPI, _):
    api.keys.set("j", api.move_down)
    api.keys.set("k", api.move_up)
    api.keys.set("i", api.edit_description)
    api.keys.set("d", api.edit_due)
    api.keys.set("r", api.edit_recurrence)
    api.keys.set("a", api.add_sibling)
    api.keys.set("z", api.toggle_expand)
    api.keys.set("Z", api.toggle_expand_parent)
    api.keys.set("gg", api.go_to_top)
    api.keys.set("G", api.go_to_bottom)
    api.keys.set("A", api.add_child_node)
    api.keys.set("J", api.shift_down)
    api.keys.set("K", api.shift_up)
    api.keys.set("xx", api.remove_node)
    api.keys.set("c", api.toggle_complete)
    api.keys.set("=,+", api.increase_urgency)
    api.keys.set("-,_", api.decrease_urgency)
    api.keys.set("/", api.start_search)
    api.keys.set("<ctrl+s>", api.start_sort)
```

--------------------------------

### Show Help Screen

Source: https://dooit-org.github.io/dooit/configuration/dooit_api.html

The `show_help` method displays the help screen within the Dooit application, providing users with assistance and information.

```python
api.show_help()
```

--------------------------------

### Todo Method - Get Siblings

Source: https://dooit-org.github.io/dooit/backend/todo.html

A method that returns a list of all sibling todos, including the current todo itself. Siblings are todos that share the same parent.

```python
siblings() -> List[Todo]

Returns the siblings for the todo (including self)
**Returns:**
Type| Default| Description  
---|---|---  
List[Self]| | List of the siblings (including self)  
```

--------------------------------

### Todo Class Method - Get All Todos

Source: https://dooit-org.github.io/dooit/backend/todo.html

A class method that retrieves all Todo objects from the database. It returns a list of all available Todo objects.

```python
all() -> List[Todo]

Returns all the todos from the database
**Returns:**
Type| Default| Description  
---|---|---  
List[Todo]| | List of the todos present in the database  
```

--------------------------------

### Define Layouts with Python

Source: https://dooit-org.github.io/dooit/extra/moving_from_v2.html

Demonstrates the new layout API in Dooit V3 using Python. It shows how to define the order of columns for workspace and todo widgets by subscribing to startup events and configuring `api.layouts`.

```python
from dooit.ui.api.widgets import TodoWidget, WorkspaceWidget

@subscribe(Startup)
def layout_setup(api: DooitAPI, _):
    api.layouts.workspace_layout = [WorkspaceWidget.description]

    api.layouts.todo_layout = [
        TodoWidget.status,
        TodoWidget.description, 
        TodoWidget.recurrence,
        TodoWidget.due,
        TodoWidget.urgency,
    ]
```

--------------------------------

### Platform Widget Usage in Python

Source: https://dooit-org.github.io/dooit-extras/widgets/platform.html

Demonstrates how to use the Platform widget within the Dooit application. It shows how to import the widget and add it to the status bar using the `subscribe` decorator for the `Startup` event.

```python
from dooit_extras.bar_widgets import Platform
from dooit.ui.api.events import subscribe, Startup

@subscribe(Startup)
def setup(api, _):
    api.bar.set(
        [
            # ....
            Platform(api),
            # ....
        ]
    )

```

--------------------------------

### Get Current Workspace Object in Dooit

Source: https://dooit-org.github.io/dooit/configuration/vars.html

Retrieve the currently selected or highlighted workspace object. If no workspace is active or selected, this method returns `None`.

```python
def current_workspace(self) -> Optional[Workspace]
```

--------------------------------

### Dooit Keybindings: Old Implementation

Source: https://dooit-org.github.io/dooit/extra/moving_from_v2.html

Illustrates the previous method of defining keybindings in Dooit using a Python dictionary. This approach maps string commands to key sequences.

```python
keybindings = {
    "switch pane": "<tab>",
    "sort menu toggle": "<ctrl+s>",
    "start search": ["/", "S"],
    "remove item": "xx",
    "edit effort": "e",
    "edit recurrence": "r",
}
```

--------------------------------

### Get Todos Tree Object in Dooit

Source: https://dooit-org.github.io/dooit/configuration/vars.html

Retrieve the object representing the tree structure of todos for the current workspace. If no workspace is active, this method returns `None`.

```python
def todos_tree(self) -> Optional[TodosTree]
```

--------------------------------

### Creating a Custom Dooit Theme (Python)

Source: https://dooit-org.github.io/dooit/configuration/theme.html

Illustrates how to create a custom theme by inheriting from `DooitThemeBase` and overriding the color properties. This allows for complete customization of the Dooit UI's color scheme.

```python
from dooit.api.theme import DooitThemeBase


class Nord(DooitThemeBase):
    _name = "dooit-nord"

    background1: str = "#2E3440"  # Darkest
    background2: str = "#3B4252"  # Lighter
    background3: str = "#434C5E"  # Lightest

    # foreground colors
    foreground1: str = "#D8DEE9"  # Darkest
    foreground2: str = "#E5E9F0"  # Lighter
    foreground3: str = "#ECEFF4"  # Lightest

    # other colors
    red: str = "#BF616A"
    orange: str = "#D08770"
    yellow: str = "#EBCB8B"
    green: str = "#A3BE8C"
    blue: str = "#81a1c1"
    purple: str = "#B48EAD"
    magenta: str = "#B48EAD"
    cyan: str = "#8fbcbb"

    # accent colors
    primary: str = cyan
    secondary: str = blue
```

--------------------------------

### Get Current Todo Item in Dooit

Source: https://dooit-org.github.io/dooit/configuration/vars.html

Retrieve the currently highlighted todo item object. If no todo item is currently selected or available, this method returns `None`.

```python
def current_todo(self) -> Optional[Todo]
```

--------------------------------

### Dooit Configuration: Workspace and TODO Settings

Source: https://dooit-org.github.io/dooit/extra/moving_from_v2.html

Defines configuration dictionaries for the Dooit workspace and TODO items. These settings control visual aspects like colors, icons, and expansion behavior, as well as structural elements like column order and hints.

```python
WORKSPACE = {
    "editing": cyan,
    "pointer": ">",
    "children_hint": "+ ",  # "[{count}]", # vars: count
    "start_expanded": False,
}

COLUMN_ORDER = ["description", "due", "urgency"]  # order of columns
TODO = {
    "color_todos": False,
    "editing": cyan,
    "pointer": ">",
    "children_hint": colored(
        " ({done}/{total})", green
    ),  # vars: remaining, done, total
    # "children_hint": "[b magenta]({remaining}!)[/b magenta]",
    "due_icon": "? ",
    "effort_icon": "+",
    "effort_color": yellow,
    "recurrence_icon": "!",
    "recurrence_color": blue,
    "tags_color": red,
    "completed_icon": "x",
    "pending_icon": "o",
    "overdue_icon": "!",
    "urgency1_icon": "A",
    "urgency2_icon": "B",
    "urgency3_icon": "C",
    "urgency4_icon": "D",
    "start_expanded": False,
    "initial_urgency": 1,
    "urgency1_color": "green",
    "urgency2_color": "yellow",
    "urgency3_color": "orange",
    "urgency4_color": "red",
}
```

--------------------------------

### Access Current Workspace via Event Subscription in Dooit

Source: https://dooit-org.github.io/dooit/configuration/vars.html

Get the currently active workspace object by subscribing to DooitEvents. This enables dynamic retrieval of the current workspace context.

```python
from dooit.ui.api.events import DooitEvent
from dooit.ui.api import DooitAPI, subscribe

@subscribe(DooitEvent)
def foo(api: DooitAPI, event: DooitEvent):
    current_workspace = api.vars.current_workspace
```

--------------------------------

### Get Workspaces Tree Object in Dooit

Source: https://dooit-org.github.io/dooit/configuration/vars.html

Retrieve the object representing the tree structure of workspaces within the Dooit application. This provides access to the hierarchical organization of user workspaces.

```python
def workspaces_tree(self) -> WorkspacesTree
```

--------------------------------

### Removing Keybinds in Python

Source: https://dooit-org.github.io/dooit/configuration/keys.html

Explains how to remove default key bindings in Python by setting the callback function to `api.no_op`. This is helpful when default key combinations conflict with user preferences or custom layouts. Removing a keybind also hides it from the help menu.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup

@subscribe(Startup)
def setup(api: DooitAPI, _):
    api.keys.set("=", api.no_op)
    api.keys.set("_", api.no_op)
```

--------------------------------

### Access Current Todo Item via Event Subscription in Dooit

Source: https://dooit-org.github.io/dooit/configuration/vars.html

Get the currently highlighted todo item by subscribing to DooitEvents. This enables dynamic retrieval of the currently focused todo.

```python
from dooit.ui.api.events import DooitEvent
from dooit.ui.api import DooitAPI, subscribe

@subscribe(DooitEvent)
def foo(api: DooitAPI, event: DooitEvent):
    current_todo = api.vars.current_todo
```

--------------------------------

### Get Current Theme Object in Dooit

Source: https://dooit-org.github.io/dooit/configuration/vars.html

Obtain the current theme object used by the Dooit application. This object provides access to styling and visual properties, allowing for theme-aware customizations.

```python
def theme(self) -> DooitThemeBase
```

--------------------------------

### Create and Apply Extra Formatters (Python)

Source: https://dooit-org.github.io/dooit/configuration/formatter.html

Shows how to create custom formatters, including 'extra formatters' that modify string representations of data. These are useful for adding prefixes, suffixes, or icons.

```python
from dooit.ui.api import DooitAPI, subscribe, extra_formatter
from dooit.ui.api.events import Startup

@extra_formatter
def due_icon(due: str, model: Todo) -> str:
    return f"📅 {due}"

@subscribe(Startup)
def set_formatters(api: DooitAPI, _):
    api.formatter.todos.due.add(due_icon)
```

--------------------------------

### Set Up Dooit Dashboard with ASCII Art and Welcome Message

Source: https://dooit-org.github.io/dooit-extras/configs/config3.html

This Python code customizes the Dooit dashboard by setting a welcome message and ASCII art. The ASCII art, featuring a "Help, I can't finish!" theme, is styled using the `Everforest` theme's primary color, with specific words highlighted. A secondary welcome message is also displayed with a bold and italic style.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from dooit.api.theme import DooitThemeBase
from dooit.ui.api.widgets import TodoWidget
from rich.style import Style
from dooit_extras.formatters import *
from dooit_extras.bar_widgets import *
from dooit_extras.scripts import *
from rich.text import Text


@subscribe(Startup)
def setup_dashboard(api: DooitAPI, _):
    theme = api.vars.theme

    ascii_art = r"""
                                                    ____
                                         v        _(    )
        _ ^ _                          v         (___(__)
       '_V/ `
       ' oX`
          X                             
          X            Help, I can't finish! 
          X          -                                      .
          X        \O/                                      |\
          X.a##a.   M                                       |_
       .aa########a.>>                                 _____|_____
    .a################aa.                              \  DOOIT  /
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"""

    ascii_art = Text(ascii_art, style=theme.primary)
    ascii_art.highlight_words([" Help, I can't finish! "], style="reverse")
    ascii_art.highlight_words([" DOOIT "], style=theme.secondary)

    header = Text(
        "Welcome again to your daily life, piled with unfinished tasks!",
        style=Style(color=theme.secondary, bold=True, italic=True),
    )

    items = [
        header,
        ascii_art,
        "",
        "",
        Text("Will you finish your tasks today?", style=theme.secondary),
    ]
    api.dashboard.set(items)

```

--------------------------------

### Get Current Application Mode in Dooit

Source: https://dooit-org.github.io/dooit/configuration/vars.html

Fetch the current operational mode of the Dooit application. The mode indicates the type of user interaction currently active, such as normal navigation, insertion, sorting, or searching.

```python
def mode(self) -> str
```

--------------------------------

### Todo Instance Methods

Source: https://dooit-org.github.io/dooit/backend/todo.html

This section details the instance methods that can be called on a Todo object to perform actions.

```APIDOC
## `method` siblings

### Description

Returns the siblings for the todo (including self).

### Method

`method`

### Endpoint

N/A (Instance method)

### Parameters

None

### Request Example

```python
todo_instance.siblings()
```

### Response

#### Success Response (200)

- **siblings_list** (`List[Todo]`) - A list of sibling Todo objects, including the instance itself.

#### Response Example

```json
[
  {
    "id": 1,
    "description": "Sibling 1"
  },
  {
    "id": 2,
    "description": "Current Todo"
  },
  {
    "id": 3,
    "description": "Sibling 2"
  }
]
```

## `method` sort_siblings

### Description

Sorts all the siblings by the given field.

### Method

`method`

### Endpoint

N/A (Instance method)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Parameters

- **field** (`str`) - Required - The field/column you'd want to sort the todo with.

### Request Example

```python
todo_instance.sort_siblings("due_date")
```

### Raises

- **AttributeError**: If an invalid field is passed.

## `method` add_todo

### Description

Adds a sub-todo to the current todo.

### Method

`method`

### Endpoint

N/A (Instance method)

### Parameters

None

### Request Example

```python
new_sub_todo = todo_instance.add_todo()
```

### Response

#### Success Response (200)

- **new_todo** (`Todo`) - The newly created and added sub-todo object.

#### Response Example

```json
{
  "id": 4,
  "description": "New Subtask",
  "parent_todo_id": 2
}
```

## `method` shift_down

### Description

Shifts the todo down by one index among its siblings. Nothing happens if it's already the last todo.

### Method

`method`

### Endpoint

N/A (Instance method)

### Parameters

None

### Request Example

```python
todo_instance.shift_down()
```

## `method` shift_up

### Description

Shifts the todo up by one index among its siblings. Nothing happens if it's already the first todo.

### Method

`method`

### Endpoint

N/A (Instance method)

### Parameters

None

### Request Example

```python
todo_instance.shift_up()
```

## `method` save

### Description

Saves any modifications done on the attributes of the todo instance to the database.

### Method

`method`

### Endpoint

N/A (Instance method)

### Parameters

None

### Request Example

```python
todo_instance.description = "Updated description"
todo_instance.save()
```

## `method` increase_urgency

### Description

Increases the urgency level for the todo by one, up to a maximum of 4.

### Method

`method`

### Endpoint

N/A (Instance method)

### Parameters

None

### Request Example

```python
todo_instance.increase_urgency()
```
```

--------------------------------

### Custom Widget Configuration (Python)

Source: https://dooit-org.github.io/dooit-extras/widgets/custom.html

This Python code demonstrates how to configure and use the Custom widget. It shows how to define functions for event subscriptions and timers, and then integrate them into the Dooit API's bar widgets.

```python
from dooit_extras.bar_widgets import Custom
from dooit.ui.api.events import subscribe, timer, Startup, TodoEvent
from dooit.ui.api import DooitAPI

@subscribe(TodoEvent)
def alert_todo_event(api: DooitAPI, event: TodoEvent):
    # ...

@timer(1)
def my_timer(api: DooitAPI, _):
    # ...

@subscribe(Startup)
def setup(api, _):
    api.bar.set( 
        [
            # ....
            Custom(api, function = alert_todo_event),
            Custom(api, function = my_timer),
            # ....
        ]
    )

```

--------------------------------

### Workspace Instance Methods: add_todo and add_workspace

Source: https://dooit-org.github.io/dooit/backend/workspace.html

Enables adding new items to a workspace. `add_todo` creates and returns a new todo associated with the workspace. `add_workspace` creates and returns a new child workspace under the current workspace.

```python
add_todo() -> Todo

add_workspace() -> Workspace
```

--------------------------------

### Set Dooit Todo Widget Layout

Source: https://dooit-org.github.io/dooit-extras/configs/config3.html

This Python code defines the layout for the `TodoWidget` in Dooit using the `Startup` event. It specifies the order in which task components like status, description, and due date are displayed. This configuration ensures a consistent and organized presentation of tasks within the Dooit interface.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from dooit.api.theme import DooitThemeBase
from dooit.ui.api.widgets import TodoWidget
from rich.style import Style
from dooit_extras.formatters import *
from dooit_extras.bar_widgets import *
from dooit_extras.scripts import *
from rich.text import Text


@subscribe(Startup)
def setup_layout(api: DooitAPI, _):
    api.layouts.todo_layout = [
        TodoWidget.status,
        TodoWidget.description,
        TodoWidget.due,
    ]

```

--------------------------------

### Todo Class Method - Get Todo by ID

Source: https://dooit-org.github.io/dooit/backend/todo.html

A class method to retrieve a Todo object by its unique identifier. It takes an ID (string or integer) as input and returns the corresponding Todo object. Raises a ValueError if an invalid ID is provided.

```python
from_id(id: str | int) -> Todo

Returns the todo object with the given id
**Parameters:**
Param| Default| Description  
---|---|---  
id| | The id of the todo object you want to get  
**Returns:**
Type| Default| Description  
---|---|---  
Self| | The todo object  
**Raises:**
Type| Default| Description  
---|---|---  
ValueError| | If an invalid ID is passed  
```

--------------------------------

### Workspace Class Methods: from_id and all

Source: https://dooit-org.github.io/dooit/backend/workspace.html

Provides class methods for the Workspace class. `from_id` retrieves a workspace by its ID, raising a ValueError for invalid IDs. `all` returns a list of all workspaces in the database.

```python
from_id(id: str | int) -> Workspace

all() -> List[Workspace]
```

--------------------------------

### Configure and Add Ticker Widget to Dooit Bar

Source: https://dooit-org.github.io/dooit-extras/widgets/ticker.html

This Python code demonstrates how to use the Ticker widget from the dooit_extras.bar_widgets module. It subscribes to the Startup event to configure the Dooit application bar, adding the Ticker widget with specified parameters such as resume and stop keys, and custom text for paused and default states.

```python
from dooit_extras.bar_widgets import Ticker
from dooit.ui.api.events import subscribe, Startup

@subscribe(Startup)
def setup(api, _):
    api.bar.set(
        [
            # ....
            Ticker(
                api,
                resume_key = "s",
                stop_key = "S",
                paused_text = "Paused",
                default_text = "No Timers",
            )
            # ....
        ]
    )
```

--------------------------------

### Workspace Instance Methods: siblings and sort_siblings

Source: https://dooit-org.github.io/dooit/backend/workspace.html

Provides instance methods for managing workspace siblings. `siblings` returns a list of sibling workspaces, including the current one. `sort_siblings` sorts these siblings by their description.

```python
siblings() -> List[Workspace]

sort_siblings()
```

--------------------------------

### Implement Workspace Progress Widget in Dooit

Source: https://dooit-org.github.io/dooit-extras/widgets/workspace_progress.html

This snippet demonstrates how to integrate the WorkspaceProgress widget into the Dooit application's status bar. It uses the `subscribe` decorator to hook into the `Startup` event and then configures the bar with the widget.

```python
from dooit_extras.bar_widgets import WorkspaceProgress
from dooit.ui.api.events import subscribe, Startup

@subscribe(Startup)
def setup(api, _):
    api.bar.set(
        [
            # ....
            WorkspaceProgress(api),
            # ....
        ]
    )
```

--------------------------------

### Navigate Dooit List

Source: https://dooit-org.github.io/dooit/configuration/dooit_api.html

Methods for navigating the todo list, including moving the cursor up or down, and jumping to the top or bottom of the list.

```python
api.move_up()
```

```python
api.move_down()
```

```python
api.go_to_top()
```

```python
api.go_to_bottom()
```

--------------------------------

### Copy Model to Clipboard

Source: https://dooit-org.github.io/dooit/configuration/dooit_api.html

The `copy_model` method copies the entire focused model (representing a todo item) to the clipboard.

```python
api.copy_model()
```

--------------------------------

### Integrate Urgency Icons Formatter in Dooit (Python)

Source: https://dooit-org.github.io/dooit-extras/formatters/urgency.html

Demonstrates how to add the Urgency Icons formatter to the Dooit application's todo formatting system. This involves subscribing to the Startup event and using the API to add the formatter, which will then be used to display urgency icons for todo items.

```python
from dooit_extras.formatters import urgency_icons
from dooit.ui.api.events import subscribe, Startup

@subscribe(Startup)
def setup(api, _):
    # ...
    api.formatter.todos.urgency.add(urgency_icons())
    # ...

```

--------------------------------

### Configure Dooit Theme with Catppuccin Colorscheme (Python)

Source: https://dooit-org.github.io/dooit-extras/configs/config2.html

This Python code defines a custom Dooit theme class named `DooitThemeCatppuccin` that inherits from `DooitThemeBase`. It sets various background, foreground, and accent colors based on the Catppuccin color palette. This theme can then be applied to the Dooit application to change its visual appearance.

```python
from dooit.api import Todo
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from dooit.api.theme import DooitThemeBase
from dooit.ui.api.widgets import TodoWidget
from rich.style import Style
from dooit_extras.formatters import *
from dooit_extras.bar_widgets import *
from dooit_extras.scripts import *
from rich.text import Text


class DooitThemeCatppuccin(DooitThemeBase):
    _name: str = "dooit-catppuccin"

    # background colors
    background1: str = "#1e1e2e"  # Darkest
    background2: str = "#313244"
    background3: str = "#45475a"  # Lightest

    # foreground colors
    foreground1: str = "#a6adc8"  # Lightest
    foreground2: str = "#bac2de"
    foreground3: str = "#cdd6f4"  # Darkest

    # other colors
    red: str = "#f38ba8"
    orange: str = "#fab387"
    yellow: str = "#f9e2af"
    green: str = "#a6e3a1"
    blue: str = "#89b4fa"
    purple: str = "#b4befe"
    magenta: str = "#f5c2e7"
    cyan: str = "#89dceb"

    # accent colors
    primary: str = purple
    secondary: str = blue


@subscribe(Startup)
def setup_colorscheme(api: DooitAPI, _):
    api.css.set_theme(DooitThemeCatppuccin)


@subscribe(Startup)
def setup_formatters(api: DooitAPI, _):
    fmt = api.formatter
    theme = api.vars.theme

    # ------- WORKSPACES -------
    format = Text(" ({}) ", style=theme.primary).markup
    fmt.workspaces.description.add(description_children_count(format))

    # --------- TODOS ---------
    # status formatter
    fmt.todos.status.add(status_icons(completed=" ", pending=" ", overdue=" "))

    # urgency formatte
    u_icons = {1: "  󰯬", 2: "  󰯯", 3: "  󰯲", 4: "  󰯵"}
    fmt.todos.urgency.add(urgency_icons(icons=u_icons))

    # due formatter
    fmt.todos.due.add(due_casual_format())
    fmt.todos.due.add(due_icon(completed="󱫐 ", pending="󱫚 ", overdue="󱫦 "))

    # effort formatter
    fmt.todos.effort.add(effort_icon(icon="󱠇 "))

    # description formatter
    format = Text("  {completed_count}/{total_count}", style=theme.green).markup
    fmt.todos.description.add(todo_description_progress(fmt=format))
    fmt.todos.description.add(description_highlight_tags(fmt=" {}"))
    fmt.todos.description.add(description_strike_completed())


@subscribe(Startup)
def setup_layout(api: DooitAPI, _):
    api.layouts.todo_layout = [
        TodoWidget.status,
        TodoWidget.effort,
        TodoWidget.description,
        TodoWidget.due,
    ]


@subscribe(Startup)
def setup_bar(api: DooitAPI, _):
    theme = api.vars.theme

    widgets = [
        TextBox(api, " 󰄛 ", bg=theme.magenta),
        Spacer(api, width=1),
        Mode(api, format_normal=" 󰷸 NORMAL ", format_insert=" 󰛿 INSERT "),
        Spacer(api, width=0),
        WorkspaceProgress(api, fmt=" 󰞯 {}% ", bg=theme.secondary),
        Spacer(api, width=1),
        Date(api, fmt=" 󰃰 {} "),
    ]
    api.bar.set(widgets)


@subscribe(Startup)
def setup_dashboard(api: DooitAPI, _):
    theme = api.vars.theme

    ascii_art = r"""
   ,-.       _,---._ __  / \
 /  )    .-'       `./ /   \
(  (   ,'            `/    /|
 \  `-"             \'\   / |
  `.              ,  \ \ /  |
   /`.          ,'-`----Y   |
  (            ;        |   '
  |  ,-.    ,-'         |  /
  |  | (   |      TODOS | /
  )  |  \  `.___________|/
  `--'   `--'    
    """

    ascii_art = Text(ascii_art, style=theme.primary)
    ascii_art.highlight_words(["TODOS"], style=theme.red)

    due_today = sum([1 for i in Todo.all() if i.is_due_today and i.is_pending])
    overdue = sum([1 for i in Todo.all() if i.is_overdue])

    header = Text(
        "Another day, another opportunity to organize my todos and then procrastinate",
        style=Style(color=theme.secondary, bold=True, italic=True),
    )

    items = [
        header,
        ascii_art,
        "",
        "",
        Text("󰠠 Tasks pending today: {}".format(due_today), style=theme.green),
        Text("󰁇 Tasks still overdue: {}".format(overdue), style=theme.red),
    ]
    api.dashboard.set(items)

```

--------------------------------

### Copy Description to Clipboard

Source: https://dooit-org.github.io/dooit/configuration/dooit_api.html

The `copy_description_to_clipboard` method copies the description of the currently selected node to the system clipboard.

```python
api.copy_description_to_clipboard()
```

--------------------------------

### Accessing Theme Colors in Dooit (Python)

Source: https://dooit-org.github.io/dooit/configuration/theme.html

Demonstrates how to access the current theme's colors within the Dooit application using the `theme` variable from `api.vars`. This allows for dynamic color retrieval for UI elements.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup

@subscribe(Startup)
def setup(api: DooitAPI, _):
    theme = api.vars.theme
    # red = theme.red
    # cyan = theme.cyan
    # so on ......
```

--------------------------------

### Manage Formatters with IDs (Python)

Source: https://dooit-org.github.io/dooit/configuration/formatter.html

Demonstrates how to add, disable, enable, and remove formatters using their unique IDs. This allows for dynamic control over how data is displayed.

```python
from dooit.ui.api import DooitAPI, subscribe
from dooit.ui.api.events import Startup
from rich.text import Text

@subscribe(Startup)
def set_formatters(api: DooitAPI, _):
    fmt = api.formatter

    fmt.workspaces.description.add(redify_important, id = "redify_important")
    fmt.todos.description.add(redify_important, id = "redify_important")
    fmt.todos.due.add(my_custom_due, "my_due")

    fmt.workspaces.description.disable("redify_important")
    fmt.workspaces.description.enable("redify_important")
    fmt.todos.description.remove("redify_important")
```

--------------------------------

### Initialize StatusIcons Widget in Dooit UI (Python)

Source: https://dooit-org.github.io/dooit-extras/widgets/status_icons.html

Demonstrates how to initialize and add the StatusIcons widget to the Dooit UI's status bar. This requires importing the StatusIcons class and subscribing to the Startup event to access the API object.

```python
from dooit_extras.bar_widgets import StatusIcons
from dooit.ui.api.events import subscribe, Startup

@subscribe(Startup)
def setup(api, _):
    api.bar.set(
        [
            # ....
            StatusIcons(api),
            # ....
        ]
    )

```