Screen Widgets

MainScreen

Bases: textual.screen.Screen

The main screen of the application.

This is the main screen of the application. It is responsible for:

handling different types of work item search
handling events for focusing different widgets based on custom key-bindings
handling the logic for creating work items
handling the logic for copying the key of the currently selected work item
handling the logic for copying the url of the currently selected work item
handling the logic for creating a local Git branch for the currently selected work item
searching Jira users for the assignee input filter
searching projects for the project input
searching types of issues for the issue type input filter
composing the widgets in the UI

See Also:

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

api

None

The API instance used by the screen to interact with the Jira REST API via a an API controller.

initial_project_key: str | None

None

A project key to set as the initial value of the projects dropdown widget.

initial_work_item_key

None

A work item key to set as the initial value of the work-item-key widget.

initial_assignee_account_id

None

Pre-selected user/assignee account id. This is passed during the initialization of the application.

initial_jql_expression_id: int | None

None

Pre-selected JQL expression ID to load into the JQL expression widget on start-up. This JQL expression will be used for searching issues when the user does not select any filter/criteria in the UI.

focus_item_on_startup

None

The position of the work item to focus and open on startup. Requires search_on_startup to be enabled.

current_loaded_work_item_key: str | None

None

Track the currently loaded work item key to prevent redundant reloads.

compose() → textual.app.ComposeResult

Composes the widgets of the application’s main screen.

Returns:: An instance of ComposeResult.

async on_mount() → None

Mounts the widgets on the screen.

This method orchestrates the initial data loading and UI population based on configuration settings and launch arguments. It performs the following operations in sequence:

Workers (Asynchronous Tasks):

Fetch projects: always runs as a worker to populate the project dropdown.
Fetch issue types: runs as a worker unless configured to only fetch projects on startup or an initial project key is provided.
Fetch statuses: runs as a worker unless configured to only fetch projects on startup or an initial project key is provided.
Fetch work items (search): runs as a worker if search_on_startup is enabled, after waiting for dependent workers to complete.
Focus item: Runs as a worker if focus_item_on_startup is specified, after waiting for the search to complete.

API Calls (Direct):

get_user(account_id): Fetches user details if initial_assignee_account_id is provided. Used to validate the user exists and retrieve their display name.

Widgets Populated:

users_selector: set with the user account ID and display name if initial_assignee_account_id is provided and the user is found via API.
jql_expression_input: set with the JQL expression if initial_jql_expression_id is provided and a matching pre-defined expression exists in configuration.
Project dropdown: populated by the fetch_projects worker.
Issue types dropdown: Populated by the fetch_issue_types worker (if applicable).
Status filter: Populated by the fetch_statuses worker (if applicable).
Work items list: Populated by the search worker (if search_on_startup is enabled).

Configuration Dependencies:

on_start_up_only_fetch_projects: If True, skips fetching issue types and statuses.
search_on_startup: If True, triggers a work item search after initial data is loaded.
pre_defined_jql_expressions: Dictionary of JQL expressions keyed by expression ID.

Execution Order:

Fetch projects (always).
Fetch issue types and statuses (conditionally, in parallel).
Fetch and set user details (conditionally).
Load and set JQL expression (conditionally).
Trigger search and focus item (conditionally, with proper await sequencing).

See the following workflow diagram for an overview.

        flowchart TD
    Start([Start]) --> FetchProjects["Run Worker: Fetch Projects<br/>(Add to workers list)"]
    FetchProjects --> CheckOnStartup{"on_start_up_only_fetch_projects<br/>is False AND<br/>initial_project_key is None?"}
    CheckOnStartup -->|Yes| FetchIssueTypes["Run Worker: Fetch Issue Types"]
    CheckOnStartup -->|Yes| FetchStatuses["Run Worker: Fetch Statuses"]
    CheckOnStartup -->|No| CheckAssignee
    FetchIssueTypes --> CheckAssignee
    FetchStatuses --> CheckAssignee
    CheckAssignee{"initial_assignee_account_id<br/>is set?"}
    CheckAssignee -->|Yes| GetUser["API Call: get_user<br/>(initial_assignee_account_id)"]
    CheckAssignee -->|No| CheckJQL
    GetUser --> UserSuccess{"user_response<br/>success?"}
    UserSuccess -->|Yes| SetUserWidget["Set users_selector<br/>with user details"]
    UserSuccess -->|No| NotifyWarning["Notify: Unable to find user<br/>with account ID"]
    SetUserWidget --> CheckJQL
    NotifyWarning --> CheckJQL
    CheckJQL{"initial_jql_expression_id<br/>is set AND<br/>pre_defined_jql_expressions exist?"}
    CheckJQL -->|Yes| GetExpression{"Get expression from<br/>pre_defined_jql_expressions?"}
    CheckJQL -->|No| CheckSearchOnStartup
    GetExpression -->|Found| SetExpression["Set jql_expression_input<br/>with expression<br/>Clean: replace newlines/tabs"]
    GetExpression -->|Not Found| CheckSearchOnStartup
    SetExpression --> CheckSearchOnStartup
    CheckSearchOnStartup{"search_on_startup<br/>is enabled?"}
    CheckSearchOnStartup -->|No| End([End])
    CheckSearchOnStartup -->|Yes| WaitWorkers["Wait for workers to complete<br/>(projects, issue types, statuses)"]
    WaitWorkers --> RunSearch["Run Worker: Search<br/>(exclusive=True)"]
    RunSearch --> CheckFocusItem{"focus_item_on_startup<br/>is set?"}
    CheckFocusItem -->|No| End
    CheckFocusItem -->|Yes| WaitSearch["Wait for search worker<br/>to complete"]
    WaitSearch --> FocusItem["Run Worker: Focus Item<br/>on Startup"]
    FocusItem --> End

Returns:: None

async fetch_projects() → None

Fetches the list of available projects.

If the user pre-selects a project using the configuration setting default_project_key_or_id or by passing the --project-key in the CLI command jiratui ui --project-key then the application will only fetch that project. This speeds up the launching of the app because less API requests are needed.

If on the other hand, no project key is pre-selected then the application will fetch all available projects. This may require multiple API requests; making the application launch slower.

If a project is pre-selected the application will pre-select the project from the dropdown list. a value if required.

If no project is found then the application will leave the dropdown empty.

Returns:: None

async fetch_statuses() → list[tuple[str, str]]

Retrieves the valid status codes depending on the selected project and type of work item.

Returns:: A list of tuples with the name and id of every project status code.

async fetch_issue_types() → list[tuple[str, str]]

Retrieves the list of type of work items.

If a project is selected then it will retrieve the types of work items associated to the project; otherwise it will retrieve all the possible types of work items.

Returns:: A list of tuples with the id of the type of issue and the name of the type of issue.

async handle_project_selection(event: textual.widgets.Select.Changed) → None

Handles the selection of a project.

This will trigger the actions to fetch the types of issues and applicable project status codes. It will also update the project key of the autocomplete widget used for searching Jira users.

Parameters:: event – the event triggered by the selection.

Returns:: Nothing.

async search_issues(next_page_token: str | None = None, search_term: str | None = None, page: int | None = None) → None

Searches work items.

If a specific issue is specified in the Issue Key input widget then the app searches the details of that issue only. If, on the other hand, no issue is specified then the app searches issues based on the given criteria.

Once the results are retrieved this method will update a reactive attribute in the search results table to update the results.

Parameters:

next_page_token – a token that identifies the next page of results.
search_term – a search term to search items using full-text search.
page – the page number to fetch results; this is only supported for Jira Data Center (aka. on-premises)

Returns:: Nothing.

async action_search(search_term: str | None = None) → None: Handles the event when the user presses the “search” button or “ctrl+r”.

action_focus_widget(key: str) → None

Focuses a widget based on the key pressed by the user.

Parameters:: key – the key the user pressed in the UI.

Returns:: Nothing.

action_copy_issue_url() → None: Copy to the clipboard the URL of the item currently selected in the search results.

action_copy_issue_key() → None: Copy to the clipboard the key of the item currently selected in the search results.

action_create_git_branch() → None: Opens up a modal screen to allow the user to create Git branches.

async action_create_work_item() → None: Handles the event to create a new work item.

async create_work_item(data: dict) → None

Handles the event to create a work item after the user clicks on the “save” button in the create-work-item screen.

Parameters:: data – a dictionary with the details of the fields and values to create the item.

Returns:: None

async fetch_issue(selected_work_item_key: str) → None

Retrieves the details of a work item selected by the user in the search results.

This is triggered from the datatable that holds the search results: IssuesSearchResultsTable

Every time a user selects a work item in the search results the application will do the following:

retrieve the details of the work item by sending a request to the API’s get_issue method.
update the information on the description tab (summary and description)
retrieve the subtasks associated to the selected work item
update the data in all the other tabs

Parameters:: selected_work_item_key – the key of the work item selected by the user from the search results datatable.

Returns:: None

async action_find_by_text() → None: Opens a screen to allow the user to enter a term to search items by text.

ServerInfoScreen

QuitScreen

class QuitScreen(name: str | None = None, id: str | None = None, classes: str | None = None)

Bases: textual.screen.ModalScreen[str]

Screen with a dialog to quit.

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

ConfirmationScreen

class ConfirmationScreen(message: str | None = None)

Bases: textual.screen.ModalScreen[bool]

Screen with a dialog to confirm an action.

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

ConfigFileScreen

class ConfigFileScreen(name: str | None = None, id: str | None = None, classes: str | None = None)

Bases: textual.screen.ModalScreen

The screen that displays the configuration settings.

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

HelpScreen

class HelpScreen(anchor: str | None = None)

Bases: textual.screen.ModalScreen

The screen that displays help.

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

ConfirmDeleteItemScreen

class ConfirmDeleteItemScreen(work_item_key: str)

Bases: textual.screen.ModalScreen[bool]

A modal screen that allows users to confirm deleting an item.

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

JQLEditorScreen

class JQLEditorScreen(content: str | None = None)

Bases: textual.screen.ModalScreen[str]

A screen that displays an editor for JQL expressions.

See Also:

Use Case: Filter-based search

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

GitScreen

class GitScreen(work_item_key: str)

Bases: textual.screen.ModalScreen[bool]

A modal screen that allows the user to create a new Git branch on a target repository.

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

TextSearchScreen

class TextSearchScreen(name: str | None = None, id: str | None = None, classes: str | None = None)

Bases: textual.screen.ModalScreen[str]

A modal screen that shows an input field to allow the user to provide a text for searching work items using full-text search.

See Also:

Use Case: Text-based search

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

DisplayTextContentScreen

class DisplayTextContentScreen(content: str, title: str | None = None)

Bases: textual.screen.ModalScreen

compose() → textual.app.ComposeResult

EditTextContentScreen

class EditTextContentScreen(content: str, jira_field_key: str, title: str | None = None)

Bases: textual.screen.Screen[dict]

A modal screen that displays a TextArea editor to allow users to edit Plain Text/Markdown content.

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

FlagWorkItemScreen

class FlagWorkItemScreen(work_item_key: str, work_item_is_flagged: bool = False)

Bases: textual.screen.Screen[dict]

A modal screen to allow the user to add/remove a flag to a work item.

The screen’s result is a dictionary with the following keys: { ‘update_flag’: if True then the issue’s flag will be added or removed. ‘note’: an optional comment. }

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

WorkItemQuickViewScreen

class WorkItemQuickViewScreen(work_item_key: str)

Bases: textual.screen.ModalScreen[str]

A modal screen that displays the details of a work item in read-only mode.

This screen can be dismissed with an optional string. The string represents the key of a work item that we want to fetch and display in the main screen. By default, the string is the key of the work item being displayed by this screen. This allows users to quickly jump to the work item being displayed.

In future versions users may be able to dismiss this screen with the key of the parent of the work item being displayed; assuming the work item has a parent.

The screen also supports the following features:

Opening the work item in the browser.
Copying to the clipboard the work item’s key.
Copying to the clipboard the work item’s URL.

See Also

Architecture

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

action_open_issue_in_browser() → None: Opens the currently-selected item in the default browser.

action_copy_issue_key() → None: Copy to the clipboard the key of the item.

action_copy_issue_url() → None: Copy to the clipboard the URL of the item.

action_search_work_item() → None: Dismisses the screen with the key of the work item being displayed.

WorkItemWorkLogScreen

class WorkItemWorkLogScreen(work_item_key: str, time_tracking: jiratui.models.TimeTracking | None = None)

Bases: textual.screen.Screen[dict]

A screen that displays the work logs of a work item.

This screen is responsible for:

fetching the logs associated to the selected work item and displaying them.
optionally fetching the work item’s current remaining time estimate; the data is not passed to the screen.
allowing the user to add and delete work logs.
opening the screen LogWorkScreen when the user presses n to add a new log entry.
handling the message UpdateLogEntry when the user updates a log entry.
handling the message LogEntryDeleted when the user deletes a log entry.

The screen can be dismissed with dictionary. This dict can contain a key called work_logs_deleted to indicate to the caller that at least 1 worklog has been deleted. This lets the caller refresh the work item (if needed) to reflect the changes to the remaining time estimate.

See Also

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

LogWorkScreen

class LogWorkScreen(work_item_key: str, mode: jiratui.widgets.work_item_worklog.screens.LogWorkScreenMode = LogWorkScreenMode.CREATE, worklog_id: str | None = None, current_remaining_estimate: str | None = None, current_time_spent: str | None = None, current_date_started: str | None = None, current_description: str | None = None)

Bases: textual.screen.Screen[jiratui.widgets.work_item_worklog.screens.LogWorkScreenResult | None]

A modal screen that allow users to provide data for creating new work log entries or updating an existing entry.

The screen’s result is an instance of LogWorkScreenResult. The object contains the values to add or update a work log entry

See Also:

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

AddRemoteLinkScreen

class AddRemoteLinkScreen(work_item_key: str | None = None)

Bases: textual.screen.Screen[dict]

A screen that allows a user to add a new remote link, aka. web link, to a work item.

See Also:

Use Case: Add Web Link

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

AddWorkItemRelationshipScreen

class AddWorkItemRelationshipScreen(work_item_key: str | None = None)

Bases: textual.screen.Screen[dict]

A modal screen that allows users to relate 2 work items.

The screen does not create the relationship between the work items. Instead, it returns the relationship’s data to the caller via the dismiss() call and the caller will proceed to create the relationship via the API.

The screen sends back the caller the following dictionary:

{
    'right_issue_key': 'WI-123',
    'link_type': 'relates-to',
    'link_type_id': 1,
}

See Also:

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

AddWorkItemScreen

class AddWorkItemScreen(project_key: str | None = None, reporter_account_id: str | None = None, parent_work_item_key: str | None = None)

Bases: textual.screen.Screen[dict[str, typing.Any]]

A modal screen for creating work items.

The screen is pushed from the main screen of the application. It is responsible for:

Displaying a form to allow the user to fill in the basic details to create the work item.
Building the required Widgets for the form based on the metadata associated to the project and type of work item being created.

The screen uses the API to:

Retrieve the list of projects
Retrieve the list of work items types associated to the selected project
Retrieve the necessary metadata for creating the work item in within the project.
Verify that the reporter provided to the screen does actually exist.

The screen can be initialized with:

A project key
The account ID of the reporter
An optional key that identifies the parent item of the work item being created. This is useful when the screen is open from the Widget that shows the list of subtasks associated to an item.

Important

This screen does not actually create the work item. Instead, upon dismissing the screen the caller will receive the necessary data to create the work item via the Jira API.

See Also:

Initialization

Initializes the screen.

Parameters:

project_key – the key of the project for which the work item will be created. If not defined the user will need to choose it from a dropdown list.
reporter_account_id – the account id of the user that acts as a reporter. This is injected from the main screen which in turn can be picked up from the cli or the configuration file. If not defined the user will need to choose it from a dropdown list.
parent_work_item_key – the key of the parent work item to which this work item belongs. If not defined the user will be able to set one.

compose() → textual.app.ComposeResult

on_mount()

Mounts the widgets.

This fetches the required data to populate the widgets.

It fetches the available projects.
It fetches the available types of issues that can be created.
If the reporter account id is set and the reporter field is editable then this will also fetch the details of the user identified by the reporter account and will set the reporter dropdown if the user exists.
It mounts the autocomplete widgets required for selecting reporter, assignee and parent key.

async fetch_available_projects() → None: Fetches the available projects and updates the project dropdown widget.

async fetch_available_issue_types(project_key: str | None = None) → None

Fetches the applicable types of work items for the selected project and updates the issue type dropdown widget.

This also removes all the dynamically-created textarea-based widgets. This does not remove the pane that contains the description widget.

Parameters:: project_key – the key of the project selected by the user.

Returns:: None

handle_project_selection() → None

Fetches the applicable types of work items for creating issues in the selected project.

This also:

updates the status of the “Save” button.
remove all the panes used for displaying textarea-based field widgets.

Returns:: None.

handle_issue_type_selection() → None

Fetches metadata for creating issues in the selected project and of the selected type.

This also updates the status of the “Save” button.

Returns:: None.

handle_reporter_selection() → None: Updates the status of the “Save” button after the user selects a Reporter.

handle_summary_value_change() → None: Updates the status of the “Save” button after the user updates the summary field.

handle_description_value_change() → None: Updates the status of the “Save” button after the user updates the description field.

async fetch_issue_create_metadata(project_key: str, issue_type_id: str) → None

Fetches the metadata for creating work items of a given type in the given project.

This function does a few things:

Retrieves the metadata for creating work items of a given type in the given project.
Builds and mounts the necessary widgets that compose the create-work-item form.

Parameters:

project_key – the key of the project for which we want to create a work item.
issue_type_id – the type of work item we want to create.

Returns:: None

handle_save() → None

Builds the necessary payload data for creating a new work item.

This does not actually create the work item. Instead, it passes the payload data to the main screen upon dismissal. The main screen is then responsible for requesting the API to create a new work item with the given payload.

Returns:: None

AddCommentScreen

class AddCommentScreen(work_item_key: str | None = None)

Bases: textual.screen.Screen[str]

A modal screen that allows users to add a comment to a work item.

The screen does not add the comment to the work item. Instead, it returns the comment’s text to the caller via the dismiss() call and the caller will proceed to add the comment via the API.

See Also:

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

ViewAttachmentScreen

class ViewAttachmentScreen(attachment_id: str, attachment_file_type: str, attachment_file_name: str)

Bases: textual.screen.ModalScreen

A modal screen to display files attached to a work item.

The screen is responsible for:

Requesting the Jira API to download a file using the attachment’s id.
Building a widget to display the contents of the file depending on the type of file.

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

AddAttachmentScreen

class AddAttachmentScreen(work_item_key: str | None = None)

Bases: textual.screen.Screen[str]

The screen to select files to attach and attach them to a work item.

The screen is responsible for:

showing a directory tree to let the user select the file to upload.
handling the Checkbox.Changed event and refreshing the directory tree when the user selects to use the last-used directory.

The screen uses the application’s session object ContextualSession to extract/store the recently-used directory.

See Also:

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

DEFAULT_ATTACHMENTS_SOURCE_DIRECTORY

‘/’

The default source directory for searching files to attach. This can be overridden by the config variable attachments_source_directory.

compose() → textual.app.ComposeResult

HistoryScreen

class HistoryScreen(manager: jiratui.utils.history.HistoryManager)

Bases: textual.screen.ModalScreen[str]

A modal screen that displays the recent history of work items viewed, created or updated.

The screen is responsible for:

retrieving the entries in the history using the HistoryManager.
deleting the history when the user requests it.
handling the message LoadWorkItem and requesting the main screen to search the work item that was selected by the user from the table.

See Also

Use Case: Manage Recent History

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult

GotToScreen

class GotToScreen(work_item_key: str, controller: jiratui.api_controller.controller.APIController)

Bases: textual.screen.ModalScreen[str]

A modal screen that display work items related to another work item.

The screen is responsible for:

Fetching the details of the given work item.
Fetching the details of the given work item’s parent (if any).
Fetching the details of the items related to the given work item.
Fetching the details of the subtasks of the given work item.
Populating data tables with basic details of all related items.
Handling the message GoToItemsTable.WorkItemSelected to request the main screen to search a work item based on its key.

See Also:

Initialization

Initialize the screen.

Parameters:

name – The name of the screen.
id – The ID of the screen in the DOM.
classes – The CSS classes for the screen.

compose() → textual.app.ComposeResult