PlaceholderTextbox.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Generic;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
 
namespace GenerallyPositive.GPALForm
{
    public class PlaceholderTextBox : TextBox
    {
        private bool isPlaceholder = false;
        private string placeholderText;
 
        public string PlaceholderText
        {
            get { return placeholderText; }
            set
            {
                placeholderText = value;
                SetPlaceholder();
            }
        }
 
        private bool _suppressPlaceholder = false;
 
        public PlaceholderTextBox()
        {
            TextChanged += OnTextChanged;
        }
 
        protected override void OnGotFocus(EventArgs e)
        {
            base.OnGotFocus(e);
 
            // clearing on focus is for placeholder text and nothing else, so what is on screen has to actually
            // be the placeholder. Taking the flag's word for it is how real text gets wiped by a click
            if (isPlaceholder && this.Text == placeholderText)
            {
                _suppressPlaceholder = true;
                isPlaceholder = false;
                this.ForeColor = System.Drawing.SystemColors.WindowText;
                this.Text = "";
                _suppressPlaceholder = false;
            }
        }
 
        protected override void OnLostFocus(EventArgs e)
        {
            base.OnLostFocus(e);
            if (!isPlaceholder && string.IsNullOrEmpty(this.Text))
                SetPlaceholder();
        }
 
        private void SetPlaceholder()
        {
            // a box with no placeholder has nothing to show. Marking it as showing one anyway makes the next
            // thing written into it look like placeholder text, and the next click wipes it: an empty box that
            // loses focus was being flagged, and OnTextChanged returns early when there is no placeholder, so
            // nothing ever cleared the flag again
            if (!isPlaceholder && !string.IsNullOrEmpty(placeholderText))
            {
                this.Text = placeholderText;
                this.ForeColor = Color.Gray;
                isPlaceholder = true;
            }
        }
 
        private void RemovePlaceHolder()
        {
            if (isPlaceholder)
            {
                this.ForeColor = System.Drawing.SystemColors.WindowText;
                isPlaceholder = false;
            }
        }
 
        private void OnTextChanged(object sender, EventArgs e)
        {
            if (_suppressPlaceholder || string.IsNullOrEmpty(placeholderText))
                return;
 
            if (this.Text.Length == 0 && !this.Focused)
                SetPlaceholder();
            else
                RemovePlaceHolder();
        }
    }
}