> For the complete documentation index, see [llms.txt](https://adaptix-framework.gitbook.io/adaptix-framework/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adaptix-framework.gitbook.io/adaptix-framework/development/axscript/axselector-type.md).

# AxSelector type

A selector is a client dialog for choosing Adaptix data. On the teamserver every `form.create_selector_*` call returns a stub and does not open a window.

## SelectorFile

The `selector_file` element contains a file path input field and a button to invoke a file selection dialog. If the `selector_file` is placed in a `container`, the file contents will be base64 encoded when generating the JSON.

<div align="left"><figure><img src="https://2104178602-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS8p8XLFtLmf0NkofQvoa%2Fuploads%2Fgit-blob-39fad6000a35066c10a7ffce12df98c73cd12c41%2FScreenshot_20251226_150625.png?alt=media" alt=""><figcaption></figcaption></figure></div>

`element create_selector_file()` - Constructs a `selector_file` element with a path field and a button that opens a file dialog. Choosing a file reads it and stores the bytes as base64. Inside a container, `toJson` writes that base64 string.

```javascript
void selector_file::setPlaceholder(string text);
string selector_file::text();          // selected path
void selector_file::setText(string path);
string selector_file::content();       // base64 of the file
void selector_file::setContent(string base64);
```

<details>

<summary>Example</summary>

```javascript
let selector = form.create_selector_file();
let btn      = form.create_button("Dump");
let tl1      = form.create_textmulti();

let container = form.create_container();
container.put("content", selector);

form.connect(btn, "clicked", function(){
    tl1.setText(container.toJson());
});

let layout = form.create_vlayout();
layout.addWidget(selector);
layout.addWidget(tl1);
layout.addWidget(btn);

let dialog = form.create_dialog("");
dialog.setSize(400, 200);
dialog.setLayout(layout);
dialog.exec();
```

<figure><img src="https://2104178602-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS8p8XLFtLmf0NkofQvoa%2Fuploads%2Fgit-blob-3661f1ffe59d67306c40cfa62378c4c1686a7f61%2FScreenshot_20250726_130408.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

***

## SelectorAgents

The `selector_agents` is a dialog window with the Sessions table and a search field. The columns that the table should have can be specified when creating `selector_agents`.

<div align="left"><figure><img src="https://2104178602-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS8p8XLFtLmf0NkofQvoa%2Fuploads%2Fgit-blob-97865865783a27c80555bbd966f1f5952f14e958%2FScreenshot_20250828_133543.png?alt=media" alt=""><figcaption></figcaption></figure></div>

`dialog create_selector_agents(string[] headers)` - Creates a `selector_agents` dialog. `headers` is an array of column keys. Omit it to use `id`, `type`, `computer`, `username`, `process`, `pid`, `os`, `tags`. Other columns: `listener`, `external_ip`, `internal_ip`, `domain`, `tid`.

#### Methods:

{% stepper %}
{% step %}

#### setSize

```javascript
void create_selector_agents::setSize(int w, int h)
```

This method sets the size for the window.
{% endstep %}

{% step %}

#### close

```javascript
void create_selector_agents::close();
```

Close window.
{% endstep %}

{% step %}

#### exec

```javascript
map(string,any)[] create_selector_agents::exec();
```

Shows the dialog as a modal dialog, blocking until the user closes it. If the window is closed by pressing the *Choose* button, the method will return an array of AGENT structures. If the window is closed otherwise, an empty array will be returned.

```javascript
// AGENT STRUCTURE:
int    agent["id"]
string agent["type"]
string agent["listener"]
string agent["external_ip"]
string agent["internal_ip"]
string agent["domain"]
string agent["computer"]
string agent["username"]    // "* " prefix when elevated, impersonated user in brackets
string agent["process"]     // "name (arch)"
string agent["pid"]
string agent["tid"]
string agent["os"]          // "windows" | "linux" | "macos" | "unknown"
string agent["tags"]
```

{% endstep %}
{% endstepper %}

<details>

<summary>Example</summary>

```javascript
let agents_selector = form.create_selector_agents(["id", "type", "computer", "username", "process", "pid", "tags"]);
agents_selector.setSize(1000, 400);

let agent_label    = form.create_label("Agent:");
let agent_text     = form.create_textline();
let select_button  = form.create_button("...");
let computer_label = form.create_label("Computer:");
let computer_text  = form.create_textline();
let username_label = form.create_label("Username:");
let username_text  = form.create_textline();

form.connect(select_button, "clicked", function(){
    let agents = agents_selector.exec();
    if (agents.length > 0) {
        let agent = agents[0];
        agent_text.setText(agent["id"]);
        computer_text.setText(agent["computer"]);
        username_text.setText(agent["username"]);
    }
});

let layout = form.create_gridlayout();
layout.addWidget(agent_label,    0, 0, 1, 1);
layout.addWidget(agent_text,     0, 1, 1, 1);
layout.addWidget(select_button,  0, 2, 1, 1);
layout.addWidget(computer_label, 1, 0, 1, 1);
layout.addWidget(computer_text,  1, 1, 1, 1);
layout.addWidget(username_label, 2, 0, 1, 1);
layout.addWidget(username_text,  2, 1, 1, 1);

let dialog = form.create_dialog("Agents info");
dialog.setSize(400, 300);
dialog.setLayout(layout);
dialog.exec();
```

<figure><img src="https://2104178602-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS8p8XLFtLmf0NkofQvoa%2Fuploads%2Fgit-blob-34a6ad2648b7bc5391bcd9c1714c5bdcda3aba67%2FScreenshot_20250828_133322.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

***

## SelectorCredentials

The `selector_credentials` is a dialog window with the *Credentials Manager* table and a search field. The columns that the table should have can be specified when creating `selector_credentials`.

<div align="left"><figure><img src="https://2104178602-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS8p8XLFtLmf0NkofQvoa%2Fuploads%2Fgit-blob-85fb38e8be1b956373d707a09c1610372c926e87%2FScreenshot_20250726_130856.png?alt=media" alt=""><figcaption></figcaption></figure></div>

`dialog create_selector_credentials(string[] headers)` - Creates a `selector_credentials` dialog. `headers` is an array of column keys. Omit it to use `username`, `password`, `realm`, `type`, `tag`, `storage`, `host`. `date` and `agent_id` are also valid columns. `exec` always returns `id` as well.

#### Methods:

{% stepper %}
{% step %}

#### setSize

```javascript
void create_selector_credentials::setSize(int w, int h)
```

This method sets the size for the window.
{% endstep %}

{% step %}

#### close

```javascript
void create_selector_credentials::close();
```

Close window.
{% endstep %}

{% step %}

#### exec

```javascript
map(string,any)[] create_selector_credentials::exec();
```

Shows the dialog as a modal dialog, blocking until the user closes it. If the window is closed by pressing the *Choose* button, the method will return an array of CRED structures. If the window is closed otherwise, an empty array will be returned.

```javascript
// CRED STRUCTURE:
string cred["username"]
string cred["password"]
string cred["realm"]
string cred["type"]
string cred["tag"]
string cred["date"]
string cred["storage"]
int    cred["agent_id"]
string cred["host"]
int    cred["id"]
```

{% endstep %}
{% endstepper %}

<details>

<summary>Example</summary>

```javascript
let creds_selector = form.create_selector_credentials(["username", "password", "realm", "tag"]);
creds_selector.setSize(800, 400);

let username_label = form.create_label("Username:");
let username_text  = form.create_textline();
let select_button  = form.create_button("...");
let password_label = form.create_label("Password:");
let password_text  = form.create_textline();
let realm_label    = form.create_label("Realm:");
let realm_text     = form.create_textline();

form.connect(select_button, "clicked", function(){
    let cred_list = creds_selector.exec();
    if (cred_list.length > 0) {
        let cred = cred_list[0];
        username_text.setText(cred["username"]);
        password_text.setText(cred["password"]);
        realm_text.setText(cred["realm"]);
    }
});

let layout = form.create_gridlayout();
layout.addWidget(username_label, 0, 0, 1, 1);
layout.addWidget(username_text,  0, 1, 1, 1);
layout.addWidget(select_button,  0, 2, 1, 1);
layout.addWidget(password_label, 1, 0, 1, 1);
layout.addWidget(password_text,  1, 1, 1, 1);
layout.addWidget(realm_label,    2, 0, 1, 1);
layout.addWidget(realm_text,     2, 1, 1, 1);

let dialog = form.create_dialog("");
dialog.setSize(400, 300);
dialog.setLayout(layout);
dialog.exec();
```

<figure><img src="https://2104178602-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS8p8XLFtLmf0NkofQvoa%2Fuploads%2Fgit-blob-2d3bb43e465f88787b8fa781449753283c30bcbc%2FScreenshot_20250726_132943.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

***

## SelectorListeners

`dialog create_selector_listeners(string[] headers)` opens the listeners table. Omit `headers` to use `name`, `type`, `protocol`, `bind_host`, `bind_port`, `status`. Other columns: `agent_addr`, `date`.

`setSize(int w, int h)`, `close()`, and `exec()` behave like the agent selector. `exec` returns an array, or an empty array if the dialog is dismissed.

```javascript
// LISTENER STRUCTURE:
string listener["name"]
string listener["type"]
string listener["protocol"]
string listener["bind_host"]
string listener["bind_port"]
string listener["agent_addr"]
string listener["status"]
string listener["date"]
```

***

## SelectorTargets

`dialog create_selector_targets(string[] headers)` opens the targets table. Omit `headers` to use `computer`, `domain`, `address`, `os`, `tag`, `alive`. Other columns: `id`, `os_desc`, `info`, `date`.

```javascript
// TARGET STRUCTURE:
int    target["id"]
string target["computer"]
string target["domain"]
string target["address"]
string target["tag"]
string target["os"]          // "windows" | "linux" | "macos" | "unknown"
string target["os_desc"]
string target["info"]
string target["date"]
bool   target["alive"]
```

The linked-agent list from `ax.targets()` is not included.

***

## SelectorDownloads

`dialog create_selector_downloads(string[] headers)` opens the downloads table. Omit `headers` to use `filename`, `agent_name`, `computer`, `total_size`, `state`. Other columns: `id`, `agent_id`, `user`, `recv_size`, `date`.

```javascript
// DOWNLOAD STRUCTURE:
int    download["id"]
int    download["agent_id"]
string download["agent_name"]
string download["user"]
string download["computer"]
string download["filename"]
int    download["total_size"]
int    download["recv_size"]
string download["state"]       // "running" | "stopped" | "finished" | "canceled"
string download["date"]
```

***

## SelectorPayloadStore

`dialog create_selector_payload_store(string[] headers)` opens the payload store. Omit `headers` to use `name`, `type`, `artifact`, `size`, `creator`, `created`. Other columns: `id`, `description`, `arch`, `listeners`, `filename`, `md5`, `sha1`, `sha256`, `tag`, `uid`, `hidden`.

```javascript
// PAYLOAD STRUCTURE:
int      payload["id"]
string   payload["name"]
string   payload["description"]
string   payload["type"]
string   payload["artifact"]
string   payload["arch"]
string[] payload["listeners"]
int      payload["size"]
string   payload["size_fmt"]
string   payload["creator"]
string   payload["created"]    // local date text, not a unix time
string   payload["filename"]
string   payload["md5"]
string   payload["sha1"]
string   payload["sha256"]
string   payload["tag"]
string   payload["uid"]
string   payload["color"]
bool     payload["hidden"]
bool     payload["missing"]
```

Each of these dialogs has `setSize(int w, int h)`, `close()`, and `exec()`. `exec` returns the selected rows, or an empty array.

***
