Program Listing for File SelectionTable.h#
↰ Return to documentation for file (include/Karana/WebUI/SelectionTable.h)
/*
* Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
*
* NOTICE TO USER:
*
* This source code and/or documentation (the "Licensed Materials") is
* the confidential and proprietary information of Karana Dynamics Inc.
* Use of these Licensed Materials is governed by the terms and conditions
* of a separate software license agreement between Karana Dynamics and the
* Licensee ("License Agreement"). Unless expressly permitted under that
* agreement, any reproduction, modification, distribution, or disclosure
* of the Licensed Materials, in whole or in part, to any third party
* without the prior written consent of Karana Dynamics is strictly prohibited.
*
* THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
* KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
* BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
* FITNESS FOR A PARTICULAR PURPOSE.
*
* IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
* INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
* OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
*
* U.S. Government End Users: The Licensed Materials are a "commercial item"
* as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
* only as a commercial end item under the terms of this license.
*
* Any use of the Licensed Materials in individual or commercial software must
* include, in the user documentation and internal source code comments,
* this Notice, Disclaimer, and U.S. Government Use Provision.
*/
#pragma once
#include "Karana/WebUI/Router.h"
#include "Karana/WebUI/Widget.h"
#include <functional>
#include <string>
#include <vector>
namespace Karana::WebUI {
/**
* @brief A table whose rows form selection options similar to radio buttons.
*
* Selection is a zero-based index, initially zero for a newly created state.
* Rows and headers must have the same width; missing cells will trigger an exception.
* Changing the number of rows resets the index to zero. An empty table or an
* index outside the rows shows no selection.
*/
class SelectionTable : public Widget {
public:
/**
* @brief Create a selectable table.
* @param router Connection router.
* @param text Label above the table.
* @param choices Rows containing text cells.
* @param headers Column labels.
* @param on_change Called with the selected row index.
* @param select_state Shared index state, or nullptr to create one initialized to zero.
* @param max_rows Nominal visible row limit; zero leaves the height unlimited.
* @param row_height Nominal row and header height in CSS pixels (default 34).
* Cells may wrap and grow taller. The scroll cap includes a nominal header plus
* max_rows rows, with an extra 25% of row_height rounded up to a whole pixel.
* @throws std::invalid_argument If a row width differs from the header width.
*/
SelectionTable(Router &router,
std::string_view text,
const std::vector<std::vector<std::string>> &choices,
const std::vector<std::string> &headers,
std::function<void(size_t)> on_change = {},
const Karana::Core::ks_ptr<State> &select_state = nullptr,
size_t max_rows = 0,
size_t row_height = 34);
/// Remove widget callbacks and the subscription to the shared selection state.
~SelectionTable() override;
/**
* @brief Select a row by its zero-based index.
* @param index Row index; an out-of-range index displays no selection.
* @param trigger_own_callback Whether to invoke this widget's callback.
*/
void setIndex(size_t index, bool trigger_own_callback = false);
/** @brief Change the nominal visible row limit without changing selection.
* @param max_rows Nominal visible row limit; zero removes the scroll-height cap.
*/
void setMaxRows(size_t max_rows);
/** @brief Change the nominal row and header height without changing selection.
* @param row_height Height in CSS pixels; cells can grow to fit wrapped text.
*/
void setRowHeight(size_t row_height);
/** @brief Replace all rows; changing their count resets the index to zero.
* @param choices New rows with one cell per current header.
* @throws std::invalid_argument For mismatched widths; deferred calls report
* through the server error handler. The previous rows remain unchanged.
*/
void setChoices(const std::vector<std::vector<std::string>> &choices);
/** @brief Replace the column labels.
* @param headers New column labels matching the current row width.
* @throws std::invalid_argument For mismatched widths; deferred calls report
* through the server error handler. The previous headers remain unchanged.
*/
void setHeaders(const std::vector<std::string> &headers);
/** @brief Replace rows and headers together, allowing the column count to change.
* @param choices New rows with one cell per new header.
* @param headers New column labels.
* @throws std::invalid_argument If a row width differs from the new headers.
* Invalid content leaves both rows and headers unchanged. A row-count
* change resets the index to zero; a same-count replacement preserves it.
*/
void setContent(const std::vector<std::vector<std::string>> &choices,
const std::vector<std::string> &headers);
protected:
/** @brief Send current rows and headers to a connecting client.
* @param client_id Client receiving the current table content.
*/
void _onConnect(int client_id) override;
private:
/// Current rows, accessed on the router event loop after construction.
std::vector<std::vector<std::string>> _choices;
/// Current column labels, accessed on the router event loop after construction.
std::vector<std::string> _headers;
/// Nominal visible row limit, accessed on the router event loop after construction.
size_t _max_rows;
/// Nominal row/header height in CSS pixels, accessed on the router event loop.
size_t _row_height;
/// Subscription used to suppress this widget's callback for programmatic selection.
Karana::Core::id_t _state_callback_id;
};
} // namespace Karana::WebUI