ex_gui_suggest.c

Completions offered under a textarea while it is typed in (headless).

Completions offered under a textarea while it is typed in (headless). n_gui_textarea_set_suggest() hands the word under the cursor to a provider and shows what it answers in a panel under the field. The keys it takes while that panel is up - Up, Down, ENTER, TAB, ESCAPE - are keys the field would otherwise use, so they are answered by the panel and the field never hears them.

The separator set is what makes it usable in a field holding a list: with "," the word being completed is the one the cursor is in, and picking one replaces that word and leaves the rest of the line alone.

Author

Castagnier Mickael

Version

1.0

Date

22/09/2026

/*
 * Nilorea Library
 * Copyright (C) 2005-2026 Castagnier Mickael
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * permissions and limitations under the License.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#define ALLEGRO_UNSTABLE 1
 
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
#include "nilorea/n_common.h"
#include "nilorea/n_gui.h"
#include "nilorea/n_log.h"

static int failures = 0;

static int asks = 0;

static char last_prefix[64] = "";

static void expect_true(const char* label, int cond) {
    if (!cond) {
        n_log(LOG_ERR, "%s: FAILED", label);
        failures++;
    } else {
        n_log(LOG_INFO, "%s: OK", label);
    }
}

static void expect_text(const char* label, const char* got, const char* want) {
    if (!got || strcmp(got, want) != 0) {
        n_log(LOG_ERR, "%s: FAILED, got \"%s\" wanted \"%s\"", label, got ? got : "(null)", want);
        failures++;
    } else {
        n_log(LOG_INFO, "%s: OK", label);
    }
}

static void vocabulary(const char* prefix, N_GUI_SUGGEST_SINK* sink, void* user_data) {
    static const char* words[] = {"sunset", "sunsets", "sunrise", "sunflower",
                                  "beach", "berlin", "bergen", NULL};
    size_t n = strlen(prefix);
    int i = 0;
 
    (void)user_data;
    asks++;
    snprintf(last_prefix, sizeof(last_prefix), "%s", prefix);
    for (i = 0; words[i]; i++) {
        if (strncasecmp(words[i], prefix, n) == 0) n_gui_suggest_add(sink, words[i]);
    }
}

static void nothing(const char* prefix, N_GUI_SUGGEST_SINK* sink, void* user_data) {
    (void)prefix;
    (void)sink;
    (void)user_data;
}

static ALLEGRO_EVENT key_event(int keycode) {
    ALLEGRO_EVENT ev;
    memset(&ev, 0, sizeof(ev));
    ev.type = ALLEGRO_EVENT_KEY_CHAR;
    ev.keyboard.keycode = keycode;
    return ev;
}

static ALLEGRO_EVENT char_event(char c) {
    ALLEGRO_EVENT ev = key_event(0);
    ev.keyboard.unichar = (int)(unsigned char)c;
    return ev;
}

static void type(N_GUI_CTX* gui, const char* s) {
    while (*s) {
        n_gui_process_event(gui, char_event(*s));
        s++;
    }
}
 
int main(void) {
    ALLEGRO_FONT* font;
    N_GUI_CTX* gui;
    int win, field, plain;
 
    set_log_level(LOG_ERR);
    if (!al_init() || !al_init_font_addon()) {
        n_log(LOG_ERR, "allegro init failed");
        return 1;
    }
    font = al_create_builtin_font(); /* no display needed */
    if (!font) {
        n_log(LOG_ERR, "al_create_builtin_font failed");
        return 1;
    }
    gui = n_gui_new_ctx(font);
    if (!gui) {
        n_log(LOG_ERR, "n_gui_new_ctx failed");
        al_destroy_font(font);
        return 1;
    }
    n_gui_set_display_size(gui, 800.0f, 600.0f);
    win = n_gui_add_window(gui, "W", 0.0f, 0.0f, 400.0f, 300.0f);
    n_gui_window_set_flags(gui, win, N_GUI_WIN_FRAMELESS);
 
    field = n_gui_add_textarea(gui, win, 0.0f, 0.0f, 300.0f, 20.0f, 0, 200, NULL, NULL);
    plain = n_gui_add_textarea(gui, win, 0.0f, 40.0f, 300.0f, 20.0f, 0, 200, NULL, NULL);
    n_gui_open_window(gui, win);
 
    /* A field with no provider is a field that behaves exactly as it did. */
    n_gui_set_focus(gui, plain);
    type(gui, "sun");
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_DOWN));
    expect_true("a field with no provider offers nothing",
                !n_gui_textarea_suggest_is_open(gui, plain));
 
    n_gui_textarea_set_suggest(gui, field, vocabulary, ",", NULL);
    n_gui_set_focus(gui, field);
 
    /* Typing opens it as soon as something matches. */
    type(gui, "sun");
    expect_true("typing opens the panel", n_gui_textarea_suggest_is_open(gui, field));
    expect_text("and the provider was given what was typed", last_prefix, "sun");
 
    /* Asked when the word under the cursor changes, and not when a key leaves
       it as it was. The cursor is at the end, so RIGHT moves nothing and asks
       nothing; LEFT shortens the word to "su" and asks once. */
    {
        int before = asks;
 
        n_gui_process_event(gui, key_event(ALLEGRO_KEY_RIGHT));
        expect_true("a key that does not change the word does not ask again",
                    asks == before);
        n_gui_process_event(gui, key_event(ALLEGRO_KEY_LEFT));
        expect_true("and one that does, asks once", asks == before + 1);
        expect_text("with the shorter word", last_prefix, "su");
        n_gui_process_event(gui, key_event(ALLEGRO_KEY_END));
    }
 
    /* ENTER takes the highlighted one, which starts on the first. */
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_ENTER));
    expect_text("ENTER puts the first one in", n_gui_textarea_get_text(gui, field), "sunset");
    expect_true("and closes the panel", !n_gui_textarea_suggest_is_open(gui, field));
 
    /* Down moves the highlight, so the second entry is reachable. */
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "sun");
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_DOWN));
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_ENTER));
    expect_text("Down then ENTER takes the second", n_gui_textarea_get_text(gui, field),
                "sunsets");
 
    /* TAB does what ENTER does, because a completion is what TAB means in a
       field that has one. */
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "sunf");
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_TAB));
    expect_text("TAB takes it too", n_gui_textarea_get_text(gui, field), "sunflower");
 
    /* ESCAPE dismisses without changing the text, and Down brings it back
       without the word having to be retyped. */
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "sun");
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_ESCAPE));
    expect_true("ESCAPE puts it away", !n_gui_textarea_suggest_is_open(gui, field));
    expect_text("and leaves the text alone", n_gui_textarea_get_text(gui, field), "sun");
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_DOWN));
    expect_true("Down asks for it again", n_gui_textarea_suggest_is_open(gui, field));
 
    /* A word nothing matches closes it rather than showing an empty panel. */
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "zzz");
    expect_true("a word nothing matches shows nothing",
                !n_gui_textarea_suggest_is_open(gui, field));
 
    /* The separator is the whole point of the feature in a list field: the
       word under the cursor is completed and the rest of the line stays. */
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "beach, sunr");
    expect_text("the provider sees only the word under the cursor", last_prefix, "sunr");
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_ENTER));
    expect_text("and only that word is replaced", n_gui_textarea_get_text(gui, field),
                "beach, sunrise");
 
    /* Nothing is added after it. A field that appended its own separator
       would be guessing that another entry is coming. */
    expect_true("and nothing was added after it",
                n_gui_textarea_get_text_length(gui, field) == strlen("beach, sunrise"));
 
    /* Completing in the middle of a line replaces that word and not the tail. */
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "berg, beach");
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_HOME));
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_RIGHT));
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_RIGHT));
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_RIGHT));
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_RIGHT));
    expect_true("the panel followed the cursor back into the first word",
                n_gui_textarea_suggest_is_open(gui, field));
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_ENTER));
    expect_text("the first word is completed and the tail is kept",
                n_gui_textarea_get_text(gui, field), "bergen, beach");
 
    /* A provider that answers nothing is not an error, it is a field with no
       completions today. */
    n_gui_textarea_set_suggest(gui, field, nothing, ",", NULL);
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "sun");
    expect_true("a provider that answers nothing shows nothing",
                !n_gui_textarea_suggest_is_open(gui, field));
 
    /* And setting NULL takes the feature off the field again. */
    n_gui_textarea_set_suggest(gui, field, vocabulary, ",", NULL);
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "sun");
    expect_true("it is on again", n_gui_textarea_suggest_is_open(gui, field));
    n_gui_textarea_set_suggest(gui, field, NULL, NULL, NULL);
    expect_true("setting NULL closes what was up",
                !n_gui_textarea_suggest_is_open(gui, field));
    type(gui, "s");
    expect_true("and stops offering", !n_gui_textarea_suggest_is_open(gui, field));
 
    /* Duplicates are refused, so a provider that walks two sources does not
       show the same word twice. */
    n_gui_textarea_set_suggest(gui, field, vocabulary, ",", NULL);
    n_gui_textarea_set_text(gui, field, "");
    type(gui, "beach");
    expect_true("an exact match still offers itself",
                n_gui_textarea_suggest_is_open(gui, field));
    n_gui_process_event(gui, key_event(ALLEGRO_KEY_ENTER));
    expect_text("and picking it changes nothing", n_gui_textarea_get_text(gui, field), "beach");
 
    /* Asking a widget that is not a textarea is answered rather than obeyed. */
    {
        int label = n_gui_add_label(gui, win, "x", 0.0f, 80.0f, 50.0f, 20.0f,
                                    N_GUI_ALIGN_LEFT);
 
        expect_true("a non-textarea has no panel", !n_gui_textarea_suggest_is_open(gui, label));
        n_gui_textarea_set_suggest(gui, label, vocabulary, ",", NULL);
        expect_true("and setting one on it does nothing",
                    !n_gui_textarea_suggest_is_open(gui, label));
    }
    expect_true("an unknown widget has no panel", !n_gui_textarea_suggest_is_open(gui, 9999));
 
    n_gui_destroy_ctx(&gui);
    al_destroy_font(font);
    if (failures) {
        n_log(LOG_ERR, "ex_gui_suggest: %d failure(s)", failures);
        return 1;
    }
    n_log(LOG_NOTICE, "ex_gui_suggest: all checks passed");
    return 0;
}