pip/libs/main/console/piscreentile.h

/*! \file piscreentile.h
 * \ingroup Console
 * \~\brief
 * \~english Base tile for the console screen tree
 * \~russian Базовый тайл для дерева консольного экрана
 */
/*
    PIP - Platform Independent Primitives
    Basic PIScreen tile
    Ivan Pelipenko peri4ko@yandex.ru

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef PISCREENTILE_H
#define PISCREENTILE_H

#include "pikbdlistener.h"
#include "pip_console_export.h"
#include "piscreentypes.h"

class PIScreenDrawer;

//! \ingroup Console
//! \~\brief
//! \~english Base tile in the console screen tree.
//! \~russian Базовый тайл в дереве консольного экрана.
class PIP_CONSOLE_EXPORT PIScreenTile: public PIObject {
	friend class PIScreen;
	PIOBJECT_SUBCLASS(PIScreenTile, PIObject);

public:
	//! \~english Constructs a tile with name, child layout direction, and size policy.
	//! \~russian Создает тайл с именем, направлением раскладки дочерних элементов и политикой размера.
	PIScreenTile(const PIString & n          = PIString(),
	             PIScreenTypes::Direction d  = PIScreenTypes::Vertical,
	             PIScreenTypes::SizePolicy p = PIScreenTypes::Preferred);

	//! \~english Destroys the tile and its owned child tiles.
	//! \~russian Уничтожает тайл и принадлежащие ему дочерние тайлы.
	virtual ~PIScreenTile();

	//! \~english Adds child tile \a t, makes this tile its parent, and attaches the subtree to the same screen bridge.
	//! \~russian Добавляет дочерний тайл \a t, делает этот тайл его родителем и подключает поддерево к тому же экранному мосту.
	void addTile(PIScreenTile * t);

	//! \~english Detaches child tile \a t without deleting it and removes its screen association.
	//! \~russian Отсоединяет дочерний тайл \a t без удаления и снимает его связь с экраном.
	void takeTile(PIScreenTile * t);

	//! \~english Removes and deletes child tile \a t.
	//! \~russian Удаляет дочерний тайл \a t и уничтожает его.
	void removeTile(PIScreenTile * t);

	//! \~english Returns the parent tile or \c nullptr for the root.
	//! \~russian Возвращает родительский тайл или \c nullptr для корня.
	PIScreenTile * parentTile() const { return parent; }

	//! \~english Returns all descendant tiles. Hidden tiles can be skipped with \a only_visible.
	//! \~russian Возвращает все дочерние тайлы по дереву. Скрытые тайлы можно пропустить через \a only_visible.
	PIVector<PIScreenTile *> children(bool only_visible = false);

	//! \~english Returns the first visible direct child covering screen point \a x, \a y.
	//! \~russian Возвращает первый видимый прямой дочерний тайл, покрывающий экранную точку \a x, \a y.
	PIScreenTile * childUnderMouse(int x, int y);

	//! \~english Makes the tile visible for subsequent layout, hit-testing, and drawing passes.
	//! \~russian Делает тайл видимым для последующих проходов компоновки, проверки попадания и отрисовки.
	void show() { visible = true; }

	//! \~english Hides the tile from layout, hit-testing, and drawing passes.
	//! \~russian Скрывает тайл из проходов компоновки, проверки попадания и отрисовки.
	void hide() { visible = false; }

	//! \~english Requests focus for this tile if it is attached to a screen and allows focus.
	//! \~russian Запрашивает фокус для этого тайла, если он подключен к экрану и допускает получение фокуса.
	void setFocus();

	//! \~english Returns whether this tile currently owns focus.
	//! \~russian Возвращает, принадлежит ли этому тайлу текущий фокус.
	bool hasFocus() const { return has_focus; }

	//! \~english Sets all margins to \a m cells.
	//! \~russian Устанавливает все отступы в \a m ячеек.
	void setMargins(int m) { marginLeft = marginRight = marginTop = marginBottom = m; }

	//! \~english Sets left, right, top, and bottom margins in cells.
	//! \~russian Устанавливает левый, правый, верхний и нижний отступы в ячейках.
	void setMargins(int l, int r, int t, int b) {
		marginLeft   = l;
		marginRight  = r;
		marginTop    = t;
		marginBottom = b;
	}

	//! \~english Returns the tile X coordinate in screen space.
	//! \~russian Возвращает координату X тайла в экранном пространстве.
	int x() const { return x_; }

	//! \~english Returns the tile Y coordinate in screen space.
	//! \~russian Возвращает координату Y тайла в экранном пространстве.
	int y() const { return y_; }

	//! \~english Returns the current tile width in cells.
	//! \~russian Возвращает текущую ширину тайла в ячейках.
	int width() const { return width_; }

	//! \~english Returns the current tile height in cells.
	//! \~russian Возвращает текущую высоту тайла в ячейках.
	int height() const { return height_; }

	//! \~english Direction used to lay out child tiles.
	//! \~russian Направление раскладки дочерних тайлов.
	PIScreenTypes::Direction direction;

	//! \~english Size policy used by the parent during layout.
	//! \~russian Политика размера, используемая родителем при компоновке.
	PIScreenTypes::SizePolicy size_policy;

	//! \~english Focus and navigation flags for the tile.
	//! \~russian Флаги фокуса и навигации для тайла.
	PIScreenTypes::FocusFlags focus_flags;

	//! \~english Background format used to prefill the tile area before drawing.
	//! \~russian Формат фона, которым предварительно заполняется область тайла перед отрисовкой.
	PIScreenTypes::CellFormat back_format;

	//! \~english Background symbol used to prefill the tile area before drawing.
	//! \~russian Символ фона, которым предварительно заполняется область тайла перед отрисовкой.
	PIChar back_symbol;

	//! \~english Minimum size limits accepted during layout.
	//! \~russian Минимальные ограничения размера, допускаемые при компоновке.
	int minimumWidth, minimumHeight;

	//! \~english Maximum size limits accepted during layout.
	//! \~russian Максимальные ограничения размера, допускаемые при компоновке.
	int maximumWidth, maximumHeight;

	//! \~english Outer margins in cells.
	//! \~russian Внешние отступы в ячейках.
	int marginLeft, marginRight, marginTop, marginBottom;

	//! \~english Spacing between visible child tiles in cells.
	//! \~russian Интервал между видимыми дочерними тайлами в ячейках.
	int spacing;

	//! \~english Whether the tile participates in layout, hit-testing, and drawing.
	//! \~russian Участвует ли тайл в компоновке, проверке попадания и отрисовке.
	bool visible;

protected:
	//! \~english Returns the preferred tile size in \a w and \a h. The base implementation derives it from visible children, spacing, and margins.
	//! \~russian Возвращает предпочтительный размер тайла в \a w и \a h. Базовая реализация вычисляет его по видимым дочерним тайлам, интервалам и отступам.
	virtual void sizeHint(int & w, int & h) const;

	//! \~english Called after the tile size changes to \a w by \a h during layout.
	//! \~russian Вызывается после изменения размера тайла до \a w на \a h во время компоновки.
	virtual void resizeEvent(int w, int h) {}

	//! \~english Draws the tile with drawer \a d in screen coordinates.
	//! \~russian Отрисовывает тайл через рисовальщик \a d в экранных координатах.
	virtual void drawEvent(PIScreenDrawer * d) {}

	//! \~english Handles keyboard input and returns \b true when the event is consumed.
	//! \~russian Обрабатывает клавиатурный ввод и возвращает \b true, если событие поглощено.
	virtual bool keyEvent(PIKbdListener::KeyEvent key) { return false; }

	//! \~english Handles mouse input and returns \b true when the event is consumed.
	//! \~russian Обрабатывает событие мыши и возвращает \b true, если событие поглощено.
	virtual bool mouseEvent(PIKbdListener::MouseEvent me) { return false; }

	//! \~english Handles mouse wheel input and returns \b true when the event is consumed.
	//! \~russian Обрабатывает колесо мыши и возвращает \b true, если событие поглощено.
	virtual bool wheelEvent(PIKbdListener::WheelEvent we) { return false; }

	//! \~english Raises tile event \a e to the owning screen bridge.
	//! \~russian Передает событие тайла \a e владеющему экранному мосту.
	void raiseEvent(PIScreenTypes::TileEvent e);

	//! \~english Attaches the tile subtree to screen bridge \a s.
	//! \~russian Подключает поддерево тайла к экранному мосту \a s.
	void setScreen(PIScreenTypes::PIScreenBase * s);

	//! \~english Deletes all owned child tiles.
	//! \~russian Удаляет все принадлежащие дочерние тайлы.
	void deleteChildren();

	//! \~english Draws background, tile contents, and then child tiles.
	//! \~russian Отрисовывает фон, содержимое тайла и затем дочерние тайлы.
	void drawEventInternal(PIScreenDrawer * d);

	//! \~english Recomputes child geometry according to size hints, margins, and policies.
	//! \~russian Пересчитывает геометрию дочерних тайлов по предпочтительным размерам, отступам и политикам.
	void layout();

	//! \~english Returns whether this tile should participate in automatic layout. Tiles with policy \a PIScreenTypes::Ignore are skipped.
	//! \~russian Возвращает, должен ли тайл участвовать в автоматической компоновке. Тайлы с политикой \a PIScreenTypes::Ignore пропускаются.
	bool needLayout() { return size_policy != PIScreenTypes::Ignore; }

	//! \~english Owned direct child tiles.
	//! \~russian Принадлежащие прямые дочерние тайлы.
	PIVector<PIScreenTile *> tiles;

	//! \~english Parent tile or \c nullptr for the root or detached tiles.
	//! \~russian Родительский тайл или \c nullptr для корня и отсоединенных тайлов.
	PIScreenTile * parent;

	//! \~english Screen bridge receiving tile notifications.
	//! \~russian Экранный мост, принимающий уведомления от тайла.
	PIScreenTypes::PIScreenBase * screen;

	//! \~english Tile position and size in screen cells.
	//! \~russian Положение и размер тайла в экранных ячейках.
	int x_, y_, width_, height_;

	//! \~english Whether this tile currently owns focus.
	//! \~russian Принадлежит ли этому тайлу текущий фокус.
	bool has_focus;

private:
	int pw, ph;
};


#endif // PISCREENTILE_H