Tical SDK

Display name of the plugin, used in logs and diagnostics.

Creates the contexts this plugin contributes. Called once at startup.

Stable unique identifier, persisted to remember the active context. Never change it between versions.

Display name shown in the context switcher.

Optional SVG path data rendered as an icon next to the name in the context switcher. Return null for no icon.

Set by the host while this context is the active one. Do not set it yourself.

The project value applied to new entries. The default ContextViewSlot.ProjectInput view edits this; custom project pickers should write their selection here.

Whether the host shows the tag editor for this context.

Whether the host shows the project input row for this context.

Whether the host shows the "add manual entry" button for this context. Defaults to true.

This is a default interface member, added after ShowTags and ShowProject, which predate the concern. Existing third-party IAppContext implementations keep compiling without picking it up explicitly.

Returns true when the entry belongs to this context and should be listed.

Stamps context-specific data (workspace, project, issue key, …) onto a new entry before it is saved.

Stable unique identifier. Also the default folder name of the plugin's sync database.

Display name shown in the context switcher.

Defaults to null.

Defaults to true.

Defaults to true. SyncedContextBase overrides it to false — its pickers replace the host's project row.

Defaults to true.

Window height in pixels while compact mode is active for this context. Defaults to 100. Raise it when you fill CompactExtra.

Lists the entries this context created — OwnsEntry(entry). Override to narrow it (the Personal context adds its active workspace) or to widen it (the tracker contexts show everything, since work tracked elsewhere can still be pushed to Jira or ClickUp).

Writes CurrentProject into entry.Project, falling back to TicalConstants.NoProject when it is blank.

Returns a two-way bound project text box for ProjectInput and CompactInline while ShowProject is true, and null otherwise. See View slots.

Defaults to null — no badge.

Defaults to an empty array.

Defaults to null — no settings section.

Returns the default plain-project editor, which mirrors the default ProjectInput view. It is created even when the project row is hidden, so the entry's project text survives an edit.

All seven default to Task.CompletedTask. See Lifecycle.

Maintained by the host. Generated from an [ObservableProperty] field, so it raises change notifications for your bindings.

The project stamped onto new entries. Bindable.

True when the entry was created under this context. The host stamps TimeEntry.ContextId once, at creation, from the active context — a context never writes it itself, so it cannot forget to claim its entries nor claim another's.

Clears CurrentProject. The [RelayCommand] generator adds ClearProjectCommand for binding.

Annotates the session and/or its entry before it is persisted.

Null when the context does not implement IContextViewProvider.

100 when the context does not implement IContextViewProvider.

Null when the context does not implement IEntryDecorator.

Empty when the context does not implement IEntryDecorator.

Null when the context does not implement IContextSettingsProvider.

Null when the context does not implement IEntryEditorProvider.

All extend IAppContext and forward to the matching IContextLifecycle member; a no-op returning Task.CompletedTask when the context does not implement it. OnEntryCompletedAsync and OnEntryUpdatedAsync take a TimeEntry; OnEntryDeletedAsync takes a Guid.

A no-op when the context does not implement ISessionAnnotator.

The host's page navigation, or null on hosts that predate this surface. Note this one extends IContextHost, not IAppContext — it reaches a host's optional capability. This is the call you do make from a plugin; see Full-screen pages.

Called once at application startup for every registered context.

Called when this context becomes the active one.

Called when another context takes over.

Called after a timer run has been stopped and the entry saved. Typical use: auto-sync to an external service. Raised for the active context.

Called after an entry was created or edited through the New/Edit window and saved. Unlike OnEntryCompleted this is raised for every registered context, not only the active one, so bookkeeping — sync status, entry links — can stay current.

Called after an entry was deleted, or merged away into another entry (its id no longer exists). Raised for every registered context. Typical use: dropping sync records and entry links kept for the entry.

Called when the user leaves the settings window, so the context can pick up changed configuration.

Returns the control for a host UI slot, or null when the slot should stay empty. Called whenever the host needs a view, so it must return a new control instance on each call. Bind the control to the context itself for state.

Window height in pixels used when compact mode is active for this context.

Title shown centered in the page header.

Called once when the page opens. It receives this page — so the content can call Close on it, for example from a clicked list row — and returns the page body.

Optional right-aligned header action, e.g. "Save" or "Refresh".

Command invoked by the header action button; ignored when ActionLabel is null or blank. Read when the page is shown — any time up to and including inside CreateContent — so it may be assigned after construction, for example to a command that captures this page and calls Close on it.

Cancelled when the page closes by any route — Close, the user going back, the host navigating elsewhere, or a second page superseding this one. Pass it into the page's async work (fetches, image loads) so the request is dropped the moment the page goes away, and no cleanup code of your own is needed.

Closes this page and completes its ShowPageAsync task with the given result. A no-op once the page has closed, so a late call can never dismiss whatever page is open by then.

Slides the page in over the main view and completes when it closes — with the value passed to Close(), or null when the user goes back or the host navigates elsewhere. Single level only: there is no page stack, so opening a second page closes the first with a null result.

The IContextNavigation implementation. Continuations run asynchronously, and a throw from ShowPage resolves the task as dismissed rather than faulting it.

Navigate to the page so it slides in over the main view. May throw — a plugin's CreateContent runs from here.

Return from the page to the main view.

Hook for thread-marshalling, e.g. onto the UI thread. Runs synchronously by default.

Call when the user left the page by another route than Close — the title-bar Settings button, say. Resolves the awaiting plugin with null instead of leaving it hanging.

Creates this context's contribution to a New/Edit entry window, or null to leave the window's built-in fields alone. Called once per window; original is the entry being edited, or null when a new entry is created.

The entry being edited, or null when the window creates a new entry.

The project text the window saves into TimeEntry.Project. Initialized from the edited entry; project slot views should write the user's choice here.

Returns the control for an edit-window slot, or null when the slot should stay empty (the host collapses it). Return a new control instance on each call and bind it to the editor itself. Defaults to null.

Called once after the window opened. Load pickers or other async state here.

The editor's preconditions for saving, evaluated in order when the user presses Save. The declarative counterpart of Validate: override this for plain "field X must be filled" rules and let the default Validate evaluate them. Re-read on every attempt, so rules may close over picker state that changes while the window is open. Defaults to empty.

Runs when the user presses Save. Returns an error message that blocks saving and is shown in the window, or null when the current input is valid. Defaults to the first unmet ValidationRules rule; override directly when the check does not fit a rule set.

Stamps context-specific data (workspace, issue marker, task link, …) onto the entry being saved, after the window applied the generic fields — description, project, date, duration, tags. Called for new and edited entries. Does nothing by default.

The "Fill Up" rounding increment in minutes for the entry being edited, or null to use the application default. Lets a context provide per-project increments.

Returns a small status badge for an entry's row in the list — "✓" pushed, "↑" pending sync — or null for none. Must be fast and non-blocking: it runs for every visible entry whenever the list is rebuilt.

Returns extra context-menu actions for an entry's row — open in browser, push now — or an empty list for none. Like GetEntryBadge this runs per visible entry and must be fast; the actions themselves may be async.

A short glyph or text — "✓", "↑".

Optional tooltip explaining the glyph. Defaults to null.

Menu item text — "Open in Jira", "Push now".

What the item does. May be async.

Optional SVG path data in the same 24×24 format as IAppContext.IconPathData. Defaults to null.

Evaluated each time the action is attempted; true when the rule passes.

Shown to the user when IsSatisfied returns false.

The first unmet rule's message, or null when every rule passes. Rules are evaluated in order and evaluation stops at the first failure, so list the most fundamental precondition first — the user is only told about one thing at a time.

Params overload of the above.

A command guarded by an arbitrary validation function. validate returns the message to report, or null to let the action run; onInvalid is where a failure message is shown, typically the context's status line.

The usual way to build one. The rules are re-read on every attempt, so a rule may close over state that changes while the button is on screen. A named factory rather than a second constructor, because a lambda argument cannot be told apart from the Func<string?> the constructor takes.

Always true — validation happens on Execute, not by disabling the control. A disabled button tells the user nothing about what is missing.

Never raised: the command is always executable, so the button never disables.

Reports the first unmet rule and does nothing else, or runs the action when all rules pass. A throwing action is caught and logged rather than escaping as an unobserved task exception — actions are expected to report their own failures.

Section title, e.g. "Jira Integration".

Optional one-line description rendered under the title.

When true, the host disables the section for unlicensed users and shows a PRO badge.

Factory for the section content. Called every time the settings window is built, so it must return a new control instance on each call.

Whether completed entries are pushed automatically. Changing it calls SaveIfLoaded().

True while a connection test is running.

The message from the last test, or null.

Drives the green/red colour of the result line.

Set to true at the end of the subclass constructor so initial property assignment does not save.

Call from the subclass's property-changed hooks to persist on change.

Persists the current values via the context settings store.

Runs the connection test and returns success plus the message to show.

Wraps TestConnectionCoreAsync with the busy flag and turns a throw into "Error: …" on the result line. Bind TestConnectionCommand, or just drop in SettingsControls.TestConnectionArea(), which wires all of it.

24×24 Material Design Icons path data: refresh arrows, upload arrow, close/clear X.

new(12, 10) — the inner padding the host applies to its ComboBox style. Mirrored here so a hand-padded control lines up with a plain picker.

A stretch combo box for picker rows, bound by property name to an items collection and a two-way selected item. Items are rendered through displayText.

A type-to-search picker for long item lists, bound like PickerComboBox. Matching is a case-insensitive substring test against displayText; focusing the empty box drops the full list down, so it still works like a combo box.

A small "minor" icon button bound to a command by name. When busyPath is given, the icon is swapped for an indeterminate progress spinner while that boolean property is true.

The small uppercase section label used by the host's New/Edit entry window.

An edit-window field in the host's convention: a FieldLabel above the control. Compose EntryEditor.BuildView slots from these.

Wrapping 11px status line, bound by property name. Without kindPath it uses the tertiary text colour; with it, the colour follows the bound SyncStatusKind — green success, orange warning, red error.

The section root: a vertical stack with the standard spacing, bound to the view model.

A labeled input with an optional 11px hint underneath. extra — a LinkHint, say — is rendered below the hint, inside the field group.

A text box bound two-way by property name; secrets are masked and get the theme's reveal-password eye toggle.

An 11px accent-coloured link that opens url in the default browser via IContextHost.OpenUrl. Place it as a field's extra ("Create an API token ↗") or as its own section row.

An int-bound NumericUpDown, whole numbers only, clamped to minimum/maximum.

A combo box with its items and selection bound two-way by property name.

Title and explanation on the left, a ToggleSwitch on the right.

The standard test-connection block for a ContextSettingsViewModelBase: a stretch action button, a thin progress bar while testing, and the result line coloured green/red by success. It binds to that base class's members by name, so the section's DataContext must be one.

A small group header for splitting a longer settings section into scannable blocks ("Durations", "Breaks"). Place it directly above the rows it introduces.

Wrapping 11px explanatory text in the tertiary text colour.

True when the service connection is configured well enough to try talking to it.

Whether completed entries are pushed automatically when the timer stops.

Fetches the selectable projects. Throw to surface a connection problem in the status line.

Fetches the selectable tasks of one project. Throw to surface a connection problem in the status line.

Pushes one completed entry to the service and returns the external key it was recorded against — issue key, task id. Throw on failure; the base marks the entry synced immediately after success, so even a crash mid-batch cannot cause duplicates.

Extracts the external key an entry was stamped with, or returns false when the entry does not belong to this service.

What the pickers show. Both default to ToString(), falling back to the empty string.

Stable identity used to restore the selection across refreshes; defaults to the display text.

Stable identity of a task, used to match a picker selection against the external key an entry was stamped with. Defaults to the display text — override it so it returns exactly that key (Jira: the issue key, ClickUp: the task id). The edit window uses it to preselect the edited entry's task.

Picker placeholders. Default to "Project" and "Task".

Default to "Configure your {Name} connection in Settings.", "Refresh projects and tasks" and "Sync pending entries to {Name}".

When true, the first project/task is selected automatically after a load. Defaults to false.

When true, the task pickers become type-to-search boxes — recommended for services where a project can hold hundreds of tasks. Defaults to false.

When true — the default — recently used tasks are listed first. Usage is recorded when a timer run completes against a task and when a task is picked in the New/Edit window; the keys persist in the sync store.

How many recently used tasks are remembered. Defaults to 10.

An entry that should be pushed, regardless of whether it already was — the base checks the sync store separately. Defaults to completed (EndTime is not null) and stamped with a key.

Called from OnSettingsChanged. Reload configuration and return true when connection settings changed, so the base can reset the pickers and reload. Defaults to true.

Override to keep a legacy database file name; defaults to sync.db in a folder named after Id.

The web page of the external item an entry is stamped with, powering the "Open in {Name}" row action, or null when none can be built. Jira: the issue's /browse page; ClickUp: the task page. Defaults to null.

Extra buttons for the main bar's action row, placed left of the standard refresh and sync buttons. Empty by default. Build them with ContextControls.IconButton so they match; the base overwrites their Margin for even spacing.

Like BuildView, this must return new control instances on every read — the main bar is built once per window, and a control can only ever have one visual parent.

The standard views. BuildMainBarView is the project and task pickers, MainBarActions, refresh and sync buttons and the status line; BuildCompactInlineView is the selected task's display text; BuildCompactExtraView is small project and task pickers as the compact window's second row.

When true — the default — the New-entry window refuses to save until a task is picked while the connection is configured. Entries created without a task could never be pushed to the service.

The project text stamped onto the entry when a task is picked in the edit window, or null to leave the entry's project text unchanged. ClickUp writes "list → task" here; Jira keeps the project text for the worklog comment. Defaults to null.

Finds the project an entry key belongs to so the edit window can preselect it (Jira: "ABC-12" → project "ABC"), or null when it cannot be derived — the window then falls back to the tracker's current project selection.

Stamps a project/task selection picked in the New/Edit window onto the entry being saved — issue marker, entry link. Called only when a task is selected; when the pickers are left empty, the entry's existing stamp is kept as is.

The host services handed to the constructor.

Durable sync bookkeeping, one database per plugin under %LocalAppData%\Tical\Plugins. See Sync store.

The picker state. Setting SelectedProject reloads the task list in the background.

True while a load or push is in flight; drives the sync button's spinner.

The status line and its severity. Assigning SyncStatus directly resets the severity to Idle, so an old error colour cannot linger under an unrelated message.

Sets the status line together with its severity. Use this rather than assigning the two properties separately.

Fire-and-forget a background operation without swallowing its exceptions: failures are routed to the status line as an error instead of disappearing silently.

Refresh reloads the projects. Sync pushes every pending, not-yet-synced entry one at a time, reporting "Syncing 2/5…" as it goes and summarising with the count of successes and failures.

Version-guarded loads: a superseded call neither overwrites the newer list nor clears its spinner. The project selection is restored by ProjectKey across a reload.

Full recompute of the pending-sync count from every entry. Called on activation and settings change; the entry hooks adjust the cached count incrementally rather than rescanning.

Already overridden for you. ShowProject is false (the pickers replace the project row) and CompactModeHeight is 140 (room for the CompactExtra picker row). The badge is "✓" once pushed and "↑" while waiting; the row actions are open-in-browser plus push/re-push. Override further only if you know what the base does.

Creates the three tables. Call it before anything else — SyncedContextBase does so in OnAppStarted.

Whether the entry has already been pushed.

Records a successful push against an external key.

Every pushed entry id, for a bulk pending calculation.

Removes the sync record of an entry, so it counts as pending again and the next sync pushes it once more. A no-op when the entry has no record.

Maps an entry to the external item it was created against.

All entry links, keyed by entry id.

Removes the entry link of an entry. A no-op when the entry has none.

Marks a task key as just used and trims the recents to the newest keep.

The recently used task keys, newest first.

Deletes sync records and entry links whose entries are not in liveEntryIds. Call only with the complete entry list — pruning against a partial list, e.g. before a cloud sync finished, loses valid records.

One-time import from a sync table created by an older plugin version in the same database file. The legacy table must have TimeEntryId and SyncedAt columns; its external-key column name is passed in. The legacy table is dropped after import. Call after InitializeAsync; a no-op when the table does not exist.

Both arguments must be valid SQL identifiers (^[A-Za-z_][A-Za-z0-9_]*$) — EntrySyncStore throws ArgumentException otherwise.

Persistent record of a time entry having been pushed. This is the source of truth for duplicate prevention — unlike tags, it is never touched by the wipe-and-reinsert entry save logic.

Maps a time entry to the external item it was created against. Unlike SyncRecord this is written when the entry is stamped, not when it is pushed — it lets a context keep the external id out of the entry's visible text.

A task the user recently tracked against, kept for most-recently-used ordering of the task picker.

Persistent storage for context configuration — API keys, URLs, options.

Read access to the user's time entries.

Opens an http(s) link in the user's default browser — "Open in Jira", token-creation pages, documentation. Other schemes are ignored. Never throws.

Control over and events from the app's single timer. Defaults to null on hosts that predate this surface — null-check it.

Desktop toast notifications. Defaults to null on hosts that predate this surface.

Write path for recording sessions outside the normal timer flow. Defaults to null on hosts that predate this surface.

Loads the settings object saved for the context, or a new default instance when none exists.

Persists the settings object for the context.

Returns all saved entries with sessions and tags populated.

Returns entries whose start time falls in the given range; either bound may be null for an open end. Prefer this over the parameterless overload when a bounded range is all you need — it avoids loading the full history for large ones.

Shows a toast notification, subject to the host's "Enable notifications" setting.

Whether the timer is currently running.

When the current run started, or null when not running.

Elapsed time of the current run, or zero when not running.

Fires when the timer starts, manually or programmatically.

Fires after the timer has stopped and the resulting entry/session has been merged and saved.

Forwarded from the host's timer tick, roughly every 200 ms while running.

Forwarded from the host's idle detection while running.

Starts the timer via the same path as the user's start button. Returns false when no host window is attached yet, or the current state does not allow starting.

Stops the timer via the same path as the user's stop button — idle prompt, merge, save. Returns false when no host window is attached yet, or nothing is running.

Appends the session to an existing entry (by id or merge match) or a new one, then saves.

Stable unique identifier, persisted if the last-used exporter is remembered. Never change it between versions.

Display name shown in the export menu — "JSON", "CSV".

Default file extension without the dot ("json", "csv"), used for the save dialog and the suggested file name. May be empty for exporters that do not write a file.

Optional SVG path data (24×24) rendered as an icon next to the name. Return null for none.

Writes the requested entries to the destination described by request.

Absolute path the user chose in the save dialog. Empty for non-file exporters.

The entries to export, already filtered by the user's date/workspace/project selection.

Maps TimeEntry.WorkspaceId to its display name; missing ids should be treated as "Unknown".

%LocalAppData%\Tical\Exporters and an Exporters folder next to the running assembly.

Loads every exporter found under the given roots, defaulting to DefaultRoots. Failures are logged per assembly and never thrown, so a broken exporter cannot break startup. Each package gets its own isolated load context that resolves shared assemblies from the host.

Primary key, defaulted to a new Guid.

Id of the context that owns this entry, stamped by the host once, when the entry is created. Contexts list their own entries by it. Rows written before this column existed are backfilled to TicalConstants.DefaultContextId.

The Personal context's sub-scoping within its own entries. Not a substitute for ContextId.

The entry's text. Project is TicalConstants.NoProject when none was set.

The runs that make up this entry. Mutating the collection, or a session already in it, marks the entry dirty.

The entry's tags.

Earliest session start, latest session end, and the sum of session durations. StartTime is DateTime.MinValue and EndTime is null when there are no sessions — an EndTime of null is how SyncedContextBase tells a still-running entry from a completed one.

hh:mm:ss and "09:00 - 11:30", for display.

Persisted snapshots of the computed values, so SQL queries can filter and sort by start time without loading every entry's sessions first. Refresh them with RefreshPersistedTimeRange() before persisting.

Dirty tracking for the save path. The overload taking a version captured earlier — before an async save — means a mutation that happened concurrently with the save is not wiped out.

Recomputes the persisted snapshots from the current sessions. Must be called before persisting the entry.

Primary key and the owning entry.

EndTime is null while the session is still running.

Replaces the clock range in the UI — this is what ISessionAnnotator writes.

When set, it is the session's duration, overriding the clock. May be negative, which is how a manual correction subtracts time.

Duration is ManualAdjustment when set, otherwise (EndTime ?? now) - StartTime — so a running session's duration grows on every read.

Maximum length of a tag's display name; longer names are truncated on assignment.

Equality and hashing are by Id alone, so two tags with the same name are still distinct.

The entry↔tag join row. Persistence plumbing — you read TimeEntry.Tags, not this.

Returns the first entry that passes filter — typically the active context's Filter — and matches on the same day, description, project and tag set, or null when there is no match. Tag comparison is order-insensitive. This is the rule the timer's stop path and IEntryRecorder both use.

Placeholder project text stamped onto entries with no project set.

Id of the built-in Personal context. Also the owner every entry written before TimeEntry.ContextId existed is backfilled to, since those entries have always been listed there.

hh:mm:ss, zero-padded, with a leading - for negative spans. Hours are not wrapped at 24. This is what FormattedDuration uses.

Drops sub-second ticks, preserving Kind.

The date's midnight plus the given time of day.

The TimeSpan overload treats an end before the start as crossing midnight and adds a day. The DateTime overload cannot — it returns TimeSpan.Zero instead.

Rounds up to the next whole minutes increment — the "Fill Up" behaviour. Returns the duration unchanged when minutes is zero or negative, or when it already lands on the increment.