TX Library Help – Version: 00173a, Revision: 171 PROJECT_BRIEF= ALL  Windows graphics in a sandbox

Технические детали

Макросы

#define _TX_VER
 Текущая версия библиотеки.
#define _TX_MODULE
 Имя модуля TXLib. Входит в диагностические сообщения.
#define __TX_COMPILER__
 Имя и версия текущего компилятора
#define _TX_BUILDMODE
 Имя режима сборки

Инициализация библиотеки

const char * txVersion () tx_nodiscard
 Возвращает строку с информацией о текущей версии библиотеки.
unsigned txVersionNumber () tx_nodiscard
 Возвращает номер версии библиотеки.
const char * txGetModuleFileName (bool fileNameOnly=true) tx_nodiscard
 Возвращает имя исполняемого файла или изначальный заголовок окна TXLib.

Настроечные константы и переменные

char _txLogName [MAX_PATH] = ""
 Имя лог-файла TXLib.
int _txWindowStyle = WS_POPUP | WS_BORDER | WS_CAPTION | WS_SYSMENU
 Стиль графического окна библиотеки.
unsigned _txCursorBlinkInterval = 500
 Интервал мигания курсора консоли (мс)
unsigned _txWindowUpdateInterval = 25
 Интервал обновления холста (мс)
const int _TX_TIMEOUT = 1000
 Таймаут операций ожидания событий (мс)
bool(* _txSwapBuffers )(HDC dest, int xDest, int yDest, int wDest, int hDest, HDC src, int xSrc, int ySrc, int wSrc, int hSrc, DWORD rOp) = NULL
 Указатель на функцию, выводящую изображение непосредственно в окно TXLib во время обработки WM_PAINT.
const unsigned _TX_BUFSIZE = 1024
 Размеры внутренних статических строковых буферов TXLib.
const unsigned _TX_BIGBUFSIZE = _TX_BUFSIZE * 2
 Размеры больших статических буферов.
const unsigned _TX_HUGEBUFSIZE = _TX_BUFSIZE * 20
 Размеры очень больших статических буферов.
const unsigned _TX_STACKSIZE = 64 * 1024
 Минимальный размер стека для потоков программы.
bool _txProcessSystemWarnings = true
 Если определено, обрабатывать ошибки в программе перед всеми другими обработчиками ошибок.
int _txWatchdogTimeout = 10*_TX_TIMEOUT
 Лимит времени на завершение программы, начиная от завершения функции main() или от вызова exit(), в мс.
#define _TX_NOINIT
 Запрет ранней инициализации TXLib.
#define TX_CONSOLE_MODE
 Режим отображения консольного окна. Допустимы любые флаги функции ShowWindow.
#define TX_CONSOLE_FONT   "Lucida Console"
 Шрифт консоли
#define TX_USE_SFML
 Макрос, разрешающий использовать TXLib вместе с графической библиотекой SFML
#define _TX_EXCEPTIONS_LIMIT   16
 Максимальное количество исключений в программе.
#define _TX_FULL_STACKTRACE
 Если определено, не исключать адреса без отладочной информации из трассировок стека.
#define _TX_WAITABLE_PARENTS
 Список запускающих программ, которые ждут нажатия клавиши после завершения процесса TXLib.
#define _TX_ALLOW_KILL_PARENT   true
 Разрешать принудительное завершение вызывающих программ, ждущих нажатия клавиш после завершения TXLib.
#define TX_COMPILED
 Макросы для поддержки прекомпиляции TX Library.
#define _TX_FATAL_EXCEPTIONS_LIMIT   16
 Максимальное количество фатальных исключений.

Внутренняя диагностика

#define _TX_ALLOW_TRACE
 Включает/отключает внутреннюю трассировку исполнения кода библиотеки.
#define TX_TRACE
 Трассирует исполнение кода через OutputDebugString().

Макросы

#define _TX_VER

Текущая версия библиотеки.

Версия библиотеки в целочисленном формате: старшее слово -- номер версии, младшее -- номер ревизии, в двоично-десятичном формате. Например, 0x172a0050 -- версия 0.172a, ревизия 50.

            #define _TX_VERSION "TXLib [Ver: 1.73a, Rev: 164, Date: 2020-01-30 05:00:00 +0300]"  //
            #define _TX_AUTHOR  "Copyright (C) Ded (Ilya Dedinsky, http://txlib.ru)"             //  ПРИМЕР
            #define _TX_VER      0x173a0000                                                      //

Эти константы автоматически обновляются при изменении версии.

См. также:
txVersion()
Примеры использования:
            #if !(defined (_TX_VER) && (_TX_VER >= 0x172a0000))
            #error Must use TXLib.h version >= 1.72 to compile this.
            #endif

См. определение в файле TXLib.h строка 138

#define _TX_MODULE

Имя модуля TXLib. Входит в диагностические сообщения.

Заметки:
Можно переопределять до включения файла TXLib.h.

См. определение в файле TXLib.h строка 159

#define _TX_NOINIT

Запрет ранней инициализации TXLib.

Если константа определена с помощью #define до включения TXLib.h в программу, ранняя инициализация (до запуска функции main) не проводится.

Заметки:
Ранняя инициализация включает:
  • Открытие окна консоли,
  • Установку кодовой страницы _TX_CODEPAGE (1251) консоли для поддержки русского языка,
  • Установку русской локали стандартной библиотеки C++ ("Russian" / "ru_RU.CP1251" и L"Russian_Russia.ACP"),
  • Переинициализация библиотек stdio и iostream на случай, если приложение не скомпоновано как консольное и библиотеки остались неинициализированы,
  • Перехват системных сигналов (деление на 0, арифметические ошибки, обращение по неверному адресу и т.д.),
  • Перехват необработанных исключений,
  • Смена заголовка консольного окна,
  • Установка режима паузы по завершении программы, чтобы окно закрывалось не сразу,
  • Подавление паузы при запуске из сред программирования, заставляющей нажимать на клавишу два раза.
Если ранняя инициализация запрещена, но в EXE-файле создается окно TXLib с помощью txCreateWindow(), то библиотека все равно будет инициализирована. В DLL ранняя инициализация никогда не проводится.

Ранняя инициализация не потокобезопасна (not thread-safe).
См. также:
txCreateWindow(), _TX_ALLOW_KILL_PARENT, _TX_WAITABLE_PARENTS, _txWatchdogTimeout, TX_CONSOLE_MODE
Примеры использования:
          #define _TX_NOINIT
          #include "TXLib.h"

См. определение в файле TXLib.h строка 5646

#define TX_CONSOLE_MODE

Режим отображения консольного окна. Допустимы любые флаги функции ShowWindow.

По умолчанию: SW_HIDE -- Скрывать консольное окно после показа графического окна.

Если ваше приложение консольное, то оно будет запускаться с открытым   черным печальным   консольным окном, которое скроется при открытии графического окна. Это может выглядеть как мигание консольного окна. Чтобы этого не было, можно создать неконсольное приложение, которое изначально запускается без видимого консольного окна и при его запуске нет эффекта такого мигания.

Создать неконсольное приложение можно:
Для компиляторов g++ (MinGW, Cygwin) и clang, используемых в CodeBlocks, CLion и т.п.   -- Указав компилятору ключ -mwindows и убрав ключ -mconsole.
Для компиляторов семейства Microsoft Visual Studio   -- Создав не проект консольного приложения, а "Desktop Application" или аналогичный.
Заметки:
Константа задается до включения файла TXLib.h в программу.

Предупреждения:
Если вы создали неконсольное приложение (см. выше), но запускаете его из среды пограммирования (например, CodeBlocks), то вы можете увидеть другое консольное окно служебной программы, с помощью которой среда программирования запускает ваше приложение. Если вы запустите ваше неконсольное приложение не из среды пограммирования, а непосредственно из Проводника, то вы не увидите никаких лишних консольных окон.
Заметки:
Btw, if you do not like that console window text is painted over graphic canvas window, set the undocumented variable _txConsole to negative value.
См. также:
_TX_NOINIT
Примеры использования:
          #define TX_CONSOLE_MODE  SW_HIDE          // Скрыть консольное окно при открытии графического окна
          #include "TXLib.h"                        // (Поведение по умолчанию)
          ...
          txCreateWindow (800, 600);

          #define TX_CONSOLE_MODE  SW_SHOW          // Всегда показывать консольное окно, например, для отладки
          #include "TXLib.h"
          ...
          txCreateWindow (800, 600);

См. определение в файле TXLib.h строка 5698

#define TX_CONSOLE_FONT   "Lucida Console"

Шрифт консоли

Заметки:
Константа задается до включения файла TXLib.h в программу.

См. определение в файле TXLib.h строка 5710

#define TX_USE_SFML

Макрос, разрешающий использовать TXLib вместе с графической библиотекой SFML

Заметки:
Этот макрос задается перед включением TXLib.h в программу.
Примеры использования:
          #define  TX_USE_SFML
          #include "TXLib.h"
          #include <SFML/Graphics.hpp>

См. определение в файле TXLib.h строка 5774

#define _TX_WAITABLE_PARENTS
Макроопределение:
"Winpty-agent.exe:Clion.exe, "            /* 0: CLion32       */ \
                                          "Winpty-agent.exe:Clion64.exe, "          /* 1: CLion64       */ \
                                          "starter.exe:eclipse.exe, "               /* 2: Eclipse 4     */ \
                                          "starter.exe:javaw.exe, "                 /* 3: Eclipse 3     */ \
                                          "cmd.exe:devenv.exe, "                    /* 4: MSVS 2003+    */ \
                                          "VSDebugConsole.exe:devenv.exe, "         /* 5: MSVS 2019+    */ \
                                          "VSDebugConsole.exe:msvsmon.exe, "        /* 6: MSVS 2022 x86 */ \
                                          "consolepauser.exe:devcpp.exe, "          /* 7: Dev-Cpp       */ \
                                          "cb_console_runner.exe:codeblocks.exe"

Список запускающих программ, которые ждут нажатия клавиши после завершения процесса TXLib.

Если программа перечислена в списке и TXLib запущена из нее, то при завершении TXLib указанная программа будет закрыта. (Это произойдет, если не открыто графическое окно TXLib, а есть только окно консоли.)

Программы разделяются пробелом или запятой. Допускается указание родителя запускающей программы, после двоеточия. Имя программы, начинающееся с большой буквы - спец. случай для консоли CLion, см. функции _txCleanup() и _txIsParentWaitable() в исходном тексте TXLib.h.

Может задаваться перед включением TXLib.h в программу.

См. также:
_TX_ALLOW_KILL_PARENT, _TX_NOINIT, _txCleanup(), _txIsParentWaitable(), _txWatchdogTimeout

См. определение в файле TXLib.h строка 5913

#define _TX_ALLOW_KILL_PARENT   true

Разрешать принудительное завершение вызывающих программ, ждущих нажатия клавиш после завершения TXLib.

Иначе отменяется собственная пауза до нажатия клавиши, встроенная в TXLib, и пусть тогда паузу делает вызывающий процесс.

Список вызывающих программ, которые могут делать такую паузу, задается в _TX_WAITABLE_PARENTS.

Заметки:
Макрос должен задаваться перед включением TXLib.h в программу.

См. также определение этой константы в файле TXLib.h.

См. также:
_TX_WAITABLE_PARENTS, _TX_NOINIT, _txWatchdogTimeout
Примеры использования:
          #define _TX_ALLOW_KILL_PARENT false
          #include "TXLib.h"

См. определение в файле TXLib.h строка 5946

#define TX_COMPILED

Макросы для поддержки прекомпиляции TX Library.

Не секрет, что файл TXLib.h очень большой и, как следствие, долго компилируется. Для ускорения сборки проектов обычно используется техника раздельной компиляции, когда в проект входят не один, а несколько .cpp-файлов. В этом случае, если изменен только один такой файл, перекомпилироваться будет только он, а результаты компиляции остальных файлов присоединяются на этапе линковки, что гораздо быстрее.

Однако библиотека TX Library представляет собой единственный заголовочный .h-файл, а заголовочные файлы перекомпилирются каждый раз, при каждой сборке. Это существенно замедляло работу с библиотекой.

Теперь файл TXLib.h внутри разделен на части, которые могут по-разному вести себя при компиляции.

Если при компиляции перед включением файла TXLib.h определен макрос TX_COMPILED, то компилироваться будет меньшая часть файла, порядка одной трети. Эта часть содержит то, что обязательно надо включать в каждую компиляцию: определения констант, структур и классов, прототипы функций, шаблоны, макросы и др. При этом около двух третей файла, которые содержат определения нешаблонных функций, не будут компилироваться. (Строго говоря, код этих двух третей обычно не помещают в заголовочные файлы, но, так как библиотека построена по принципу единственного файла для упрощения работы с ней, такой код она вынуждена содержать.)

Чтобы в проекте были доступны откомпилированные определения всех необходимых функций библиотеки, в него нужно добавить еще один файл, включив в него @с TXLib.h и определив в нем макрос TX_COMPILING. Это приведет к компиляции всего содержимого библиотеки, и ее машинный код станет доступен всей программе. В примере ниже этот файл назван TXLib.cpp, но имя может быть любое. Для компиляции этого файла потребуется время, но затем он перестанет участвовать в компиляции, так как его содержимое не будет изменяться, и общее время сборки проекта сократится, от 1.5 до 3 раз.

Предупреждения:
Не следует помещать в этот файл ничего, кроме директив #define TX_COMPILING и #include "TXLib.h", так как при изменении содержимого этого файла среда программирования снова перекомпилирует его, на что вновь потребуется большое время.

Также для ускорения компиляции можно определить макрос WIN32_LEAN_AND_MEAN до включения TXLib.h в программу.

Предупреждения:
Макрос WIN32_LEAN_AND_MEAN задается автоматически при задании макроса TX_COMPILED. Если при этом не видны определения каких-либо сущностей, определенных в Windows.h (функций, структур, классов, констант и т.п.), включите в программу файлы, определяющие эти сущности, вручную.
Заметки:
Если определены макросы TX_COMPILED или TX_COMPILING, анонимное пространство имен, окружающее пространство имен TX, не используется.
Примеры использования:
          // Оба файла ниже должны входить в один и тот же проект Visual Studio или другой среды
          // программирования (IDE). Для добавления файла в проект используйте возможности вашей среды
          // программирования.

          //-----------------------------------------------
          // Main.cpp: Файл с текстом программы
          //-----------------------------------------------

          #define   TX_COMPILED   // Обязательно ПЕРЕД командой #include
          #include "TXLib.h"

          int main()
              {
              txCreateWindow (800, 600);
              ...
              }

          //-----------------------------------------------
          // TXLib.cpp: Файл для прекомпиляции TXLib
          //-----------------------------------------------

          #define   TX_COMPILING  // Обязательно ПЕРЕД командой #include
          #include "TXLib.h"

          // [Больше в этом файле ничего нет]

См. определение в файле TXLib.h строка 6043

#define _TX_ALLOW_TRACE

Включает/отключает внутреннюю трассировку исполнения кода библиотеки.

Трассировка идет через макрос TX_TRACE, который подставляется перед каждым оператором (statement). По умолчанию трассировка выключена.

По умолчанию трассировка ведется через функцию OutputDebugString(), ее вывод можно перехватить утилитами-логгерами, например, DbgView. Это можно изменить, переопределив макрос TX_TRACE до включения TXLib.h в программу.

Предупреждения:
Трассировка очень тормозит выполнение программы, особенно при отладке в Microsoft Visual Studio. В этом случае лучше пользоваться DbgView (см. выше) и запускать отлаживаемую программу отдельно, а не из-под отладчика Visual Studio.
Заметки:
_TX_ALLOW_TRACE и TX_TRACE задаются перед включением TXLib.h в программу.
Уровни трассировки:
1   Regular functions
2   Reserved
3   Init/Cleanup
4   Init/Cleanup, misc functions
5   Error handling, entry points
6   Error handling, main part
7   Error handling, misc functions
8   Canvas worker thread
9   Reserved
Примеры использования:
          // Для просмотра трассы запустите DbgView ДО запуска программы!

          #define  _TX_ALLOW_TRACE 1  // Трассировать только обычные функции TXLib (уровень 1).
          #include "TXLib.h"

          #define  _DEBUG             // Не трассировать, но собирать информацию о вызовах
          #include "TXLib.h"          // функций TXLib для возможной трассировки стека.

См. определение в файле TXLib.h строка 6101

#define TX_TRACE

Трассирует исполнение кода через OutputDebugString().

По умолчанию трассировка ведется через функцию OutputDebugString(), ее вывод можно перехватить утилитами-логгерами, например, DbgView. Для "раскраски" лога есть файл TX\Dev\DbgView.ini, его надо загрузить в DbgView через меню Edit/Filter/Load (Ctrl+L).

С помощью TX_TRACE можно трассировать код самой библиотеки TXLib. Для этого надо разрешить трассировку TXLib, определив макрос _TX_ALLOW_TRACE перед включением файла TXLib.h в программу. По умолчанию трассировка TXLib выключена.

TX_TRACE можно переопределить в свой код. Тогда, если трассировка библиотеки разрешена, он будет вызываться почти перед каждой исполняемой строкой TXLib. Может быть, это кому-нибудь будет интересно.

Примеры использования:
          int main()
              {
              ...
              TX_TRACE;  // Через DbgView увидим имя файла и номер выполняемой строки
              ...
              }
          #define  TX_TRACE  printf (__TX_FILELINE__ "\t" __TX_FUNCTION__ "\n");
          #include "TXLib.h"

См. определение в файле TXLib.h строка 6137


Функции

const char* txVersion ( )

Возвращает строку с информацией о текущей версии библиотеки.

Возвращает:
Строка с информацией о текущей версии библиотеки.
Примеры использования:
          printf ("I personally love %s\n", txVersion());
unsigned txVersionNumber ( )

Возвращает номер версии библиотеки.

Возвращает:
Номер версии библиотеки.
Примеры использования:
          printf ("My magic number is %x\n", txVersionNumber());
const char* txGetModuleFileName ( bool  fileNameOnly = true)

Возвращает имя исполняемого файла или изначальный заголовок окна TXLib.

Аргументы:
fileNameOnlyВозвратить только полное имя исполняемого файла, полученного через Win32 функцию GetFileModuleName (NULL, ...). Необязательно. Если не указано, то возвращается полное имя исполняемого файла.
Возвращает:
fileNameOnly = true: Имя исполняемого файла.
fileNameOnly = false: Изначальный заголовок окна TXLib.
Заметки:
Возвращается статическая строка.
См. также:
txWindow(), txVersion(), txVersionNumber()
Примеры использования:
          printf ("Смотрите на заголовок окна!");

          for (int done = 0; done <= 100; done++)
              {
              char title [1024] = "";
              sprintf (title, "%s - [%-10.*s] %d%%", txGetModuleFileName (false), done/10, "||||||||||", done);

              SetWindowText (txWindow(), title);
              SetWindowText (Win32::GetConsoleWindow(), title);
              txSleep (50);
              }

          txMessageBox ("Вот такой вот progress bar", "TXLib forever)");

Переменные

char _txLogName = ""

Имя лог-файла TXLib.

В эту строку надо скопировать нужное вам имя лог-файла.

По умолчанию файл создается во время ошибки в одной папке с запущенной программой, имеет то же имя, что и файл программы, с добавлением расширения ".log".

Заметки:
Устанавливать имя лог-файла надо в начале работы программы, до появления первой ошибки.

См. определение в файле TXLib.h строка 5599

int _txWindowStyle = WS_POPUP | WS_BORDER | WS_CAPTION | WS_SYSMENU

Стиль графического окна библиотеки.

Заметки:
Переменная устанавливается до открытия окна библиотеки.
Примеры использования:
          _txWindowStyle &= ~WS_CAPTION; // FullScreen: окно без заголовка, размером с экран
          txCreateWindow (GetSystemMetrics (SM_CXSCREEN), GetSystemMetrics (SM_CYSCREEN));

          printf ("Закройте меня через Alt+F4\n");

См. определение в файле TXLib.h строка 5729

unsigned _txWindowUpdateInterval = 25

Интервал обновления холста (мс)

Заметки:
Переменная устанавливается до открытия окна библиотеки.

См. определение в файле TXLib.h строка 5756

bool(* _txSwapBuffers)(HDC dest, int xDest, int yDest, int wDest, int hDest, HDC src, int xSrc, int ySrc, int wSrc, int hSrc, DWORD rOp) = NULL

Указатель на функцию, выводящую изображение непосредственно в окно TXLib во время обработки WM_PAINT.

Если равен NULL, то используется Win32::BitBlt.

Вы можете переопределить значение этого указателя, чтобы он указывал на вашу функцию, и тогда TXLib будет выводить изображение в окно через нее. Имейте в виду, что эта функция будет вызываться в отдельном потоке.

Параметры этой функции гуглите: "StretchBlt function".

См. также:
txSetWindowsHook(), txBitBlt(), txAlphaBlend()
Примеры использования:
          #include "TXLib.h"

          bool MySwapBuffers (HDC dest, int xDest, int yDest, int wDest, int hDest,
                              HDC src,  int xSrc,  int ySrc,  int wSrc,  int hSrc, DWORD rOp)
              {
              return txAlphaBlend (dest, xDest, yDest, wSrc-xSrc, hSrc-ySrc, src, xSrc, ySrc, 0.01);
              }

          int main()
              {
              _txSwapBuffers = MySwapBuffers;  // That's it

              txCreateWindow (800, 600);

              txSetFillColor (TX_NULL);
              txRectangle (10, 10, txGetExtentX() - 10, txGetExtentY() - 10);

              for (int x = 50; x <= txGetExtentX() - 50; x += 20)
                  {
                  txCircle (x, txGetExtentY()/2, 10);
                  txSleep (100);
                  }

              txSleep (3000);
              }

См. определение в файле TXLib.h строка 5842

Лимит времени на завершение программы, начиная от завершения функции main() или от вызова exit(), в мс.

Если значение меньше 0, то время не лимитируется.

Заметки:
Для предотвращения зависания программы при выходе TXLib запускает отдельный сторожевой поток (watchdog thread), который ожидает _txWatchdogTimeout миллисекунд, а затем принудительно завершает программу.
См. также:
_TX_WAITABLE_PARENTS, _TX_NOINIT

См. определение в файле TXLib.h строка 5963